In this directory we provide the apply.lisp book, which makes available
the functions:

(apply$ fn args)     - applies the warranted function fn to args

(ev$ x a)            - evaluates an expression x composed of warranted
                       functions under an alist a binding the variable
                       symbols

(def-warranted fn)   - analyzes a defun'd function and makes it warranted,
                       if possible.  If successful, this function creates the
                       0-ary predicate APPLY$-WARRANT-fn, which hypothesizes
                       that apply$ fn works appropriately for fn.  These
                       predicates are called ``warrants'' for their respective
                       functions.  Warrants are required in any theorem
                       involving the application via apply$ of user-defined
                       functions.

(defun$ fn ...)      - like defun but then makes fn warranted, if possible

Apply$ and ev$ are not, in general, executable at the top-level of the ACL2
loop because of the involvement of certain undefined (constrained) functions
namely badge-userfn and apply$-userfn.

This directory also contains the books user-book.lisp and foldr-exercises.lisp
that contain many defun$ forms and some theorems about various mapping
functions.

This directory also contains the book doppelgangers.lisp which demonstrates
that we can define versions of badge-userfn and apply$-userfn, called their
``doppelgangers,'' that we can attach to those two constrained functions to
obtain an evaluation theory suitable for all the functions in user-book.lisp.
Not only can we then execute (at the top-level of the ACL2 loop) forms
ancestrally involving apply$, but we can prove that all the warrants issued in
user-book.lisp are valid.  This demonstrates, at least for user-book, that the
theorems we prove about mapping functions like collect and foldr -- which are
burdened by those odd warrant hypotheses -- are not vacuously true because
there's no way the warrants are true.

Unfortunately, the demonstration of successful attachments to make an effective
evaluation theory for user-book.lisp does not solve the problem of evaluation
for other books built on apply$.  That is, apply$ is just not evaluable.

We are working on improving that situation.

To certify all the books on this directory,

(ld "script.lsp" :ld-pre-eval-print t)

You should read script.lsp to see that doppelgangers can be attached
to the two constrained functions and to see how we show that all
warrants are valid in the resulting evaluation theory for user-book.
