This is acl2-doc-emacs.info, produced by makeinfo version 4.13 from
acl2-doc-emacs.texinfo.

This is documentation for ACL2 Version 6.3
Copyright (C) 2013  University of Texas at Austin

This program is free software; you can redistribute it and/or modify
it under the terms of Version 2 of the GNU General Public License as
published by the Free Software Foundation.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Written by:  Matt Kaufmann and J Strother Moore
Department of Computer Sciences
University of Texas at Austin
Austin, TX 78712-1188 U.S.A.

INFO-DIR-SECTION Math
START-INFO-DIR-ENTRY
* acl2: (acl2-doc-emacs). Applicative Common Lisp
END-INFO-DIR-ENTRY


File: acl2-doc-emacs.info,  Node: PARALLEL-PROGRAMMING,  Next: PARALLEL-PROOF,  Prev: COMPILING-ACL2P,  Up: PARALLELISM

PARALLEL-PROGRAMMING    parallel programming in ACL2(p)

Here we document support for parallel programming in ACL2(p), an
experimental extension of ACL2; also see *note PARALLELISM::.

* Menu:

* DEFLOCK:: define a wrapper macro that provides mutual exclusion in ACL2(p)

* EARLY-TERMINATION:: early termination for pand and por.

* ERROR-TRIPLES-AND-PARALLELISM:: how to avoid error triples in ACL2(p)

* GRANULARITY:: limit the amount of parallelism

* PAND:: parallel, Boolean version of and

* PARALLEL-EXECUTION:: for ACL2(p): configure parallel execution

* PARALLELISM-AT-THE-TOP-LEVEL:: parallel execution in the ACL2 top-level loop

* PARALLELISM-PERFORMANCE:: performance issues for parallel execution

* PARALLELISM-TUTORIAL:: a tutorial on how to use the parallelism library.

* PARGS:: parallel evaluation of arguments in a function call

* PLET:: parallel version of let

* POR:: parallel, Boolean version of or

* SPEC-MV-LET:: modification of mv-let supporting speculative and parallel execution

* WITH-OUTPUT-LOCK:: provides a mutual-exclusion mechanism for performing output in parallel


Related topics other than immediate subtopics:
* SET-PARALLEL-EXECUTION:: for ACL2(p): enabling parallel execution for four parallelism primitives

* SET-TOTAL-PARALLELISM-WORK-LIMIT:: for ACL2(p): set thread limit for parallelism primitives

One of ACL2's strengths lies in its ability to execute industrial models
efficiently.  The ACL2 source code provides an experimental parallel
execution capability that can increase the speed of explicit evaluation,
including simulator runs using such models, and it can also decrease
the time required for proofs that make heavy use of the evaluation of
ground terms.

The parallelism primitives are plet, pargs, pand, por, and spec-mv-let.
Pand and por terminate early when an argument is found to evaluate to
nil or non-nil, respectively, thus potentially improving on the
efficiency of lazy evaluation.  Spec-mv-let is a modification of mv-let
that supports speculative and parallel execution.

Of the above five parallelism primitives, all but spec-mv-let allow for
limiting parallel execution (spawning of so-called "threads") depending
on resource availability.  Specifically, the primitives allow
specification of a size condition to control the granularity under
which threads are allowed to spawn.  You can use such granularity
declarations in recursively-defined functions to implement
data-dependent parallelism in their execution.

We recommend that in order to learn to use the parallelism primitives,
you begin by reading examples: see *note PARALLELISM-TUTORIAL::.  That
section will direct you to further documentation topics.

In addition to providing parallel programming primitives, ACL2(p) also
provides the ability to execute the main ACL2 proof process in parallel.
See *note SET-WATERFALL-PARALLELISM:: for further details.


File: acl2-doc-emacs.info,  Node: DEFLOCK,  Next: EARLY-TERMINATION,  Prev: PARALLEL-PROGRAMMING,  Up: PARALLEL-PROGRAMMING

DEFLOCK    define a wrapper macro that provides mutual exclusion in ACL2(p)

This documentation topic relates to the experimental extension of ACL2
supporting parallel evaluation and proof; see *note PARALLELISM::.

     Example Form:
     (deflock *my-lock*)

     General Form:
     (deflock *symbol*)

where *symbol* is a symbol whose first and last characters are both the
character #\*.

A call of this macro generates a definition of another macro, named
with-<modified-lock-symbol>, where <modified-lock-symbol> is the given
symbol with the leading and trailing * characters removed.  This newly
defined macro will guarantee mutually exclusive execution when called
in the body of the raw Lisp definition of a function, as is typically
the case for guard-verified functions, for :program mode functions, and
for calls of macro top-level.  (See *note GUARD-EVALUATION-TABLE:: for
details of how raw Lisp code might not be invoked when guard-checking
(see *note SET-GUARD-CHECKING::) has value :none or :all.)

To see how mutual exclusion is guaranteed, consider the raw Lisp code
generated for the macro, with-<modified-lock-symbol>, that is introduced
by a call of deflock.  This code uses a lock (with the given *symbol*
as its name), which guarantees that for any two forms that are each in
the scope of a call of with-<modified-lock-symbol>, the forms do not
execute concurrently.

Note that a call of deflock expands into the application of progn to
two events, as illustrated below.

     ACL2 !>:trans1 (deflock *my-cw-lock*)
      (PROGN (TABLE LOCK-TABLE '*MY-CW-LOCK* T)
             (DEFMACRO WITH-MY-CW-LOCK (&REST ARGS)
                       (LIST* 'WITH-LOCK '*MY-CW-LOCK* ARGS)))
     ACL2 !>

Thus, deflock forms are legal embedded event forms (see *note
EMBEDDED-EVENT-FORM::) for books as well as encapsulate and progn
events.

The following log shows a lock in action.  Recall that locks work as
expected in guard-verified and :program mode functions; they do not,
however, work in :logic mode functions that have not been
guard-verified, as illustrated below.

     ACL2 !>(deflock *my-cw-lock*)
     [[.. output omitted ..]]
      WITH-MY-CW-LOCK
     ACL2 !>(defun foo (n)
              (declare (xargs :guard (natp n) :verify-guards nil))
              (plet ((x1 (with-my-cw-lock (cw "~x0" (make-list n))))
                     (x2 (with-my-cw-lock (cw "~x0" (make-list n)))))
                    (and (null x1) (null x2))))
     [[.. output omitted ..]]
      FOO
     ACL2 !>(foo 20)
     (NIL NIL NIL NIL( NIL NIL NIL NIL NIL NILNIL  NIL NILNIL  NIL NILNIL
          NIL NILNIL NIL  NIL NILNIL  NIL NIL
     NIL      NILNIL  NIL NILNIL )
     NIL NIL NIL NIL NIL NIL NIL NIL)
     T
     ACL2 !>(verify-guards foo)
     [[.. output omitted ..]]
      FOO
     ACL2 !>(foo 20)
     (NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL
          NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL)
     (NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL
          NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL)
     T
     ACL2 !>


File: acl2-doc-emacs.info,  Node: EARLY-TERMINATION,  Next: ERROR-TRIPLES-AND-PARALLELISM,  Prev: DEFLOCK,  Up: PARALLEL-PROGRAMMING

EARLY-TERMINATION    early termination for pand and por.

This documentation topic relates to the experimental extension of ACL2
supporting parallel execution and proof; see *note PARALLELISM::.

The evaluation of (and expr1 expr2) returns nil if expr1 evaluates to
nil, avoiding the evaluation of expr2.  More generally, the evaluation
of (and expr1 expr2 ... exprk) terminates with a return value of nil as
soon as any expri evaluates to nil -- no exprj is evaluated in this
case for j > i.  This so-called "lazy evaluation" of and terms can thus
save some computation; roughly speaking, the smaller the i, the more
computation is saved.

If the above call of and is replaced by its parallel version, pand,
then there can be even more opportunity for skipping work.  The
arguments to pand can be evaluated in parallel, in which case the first
such evaluation that returns with a value of nil, if any, causes the
remaining such evaluations to abort.

Consider the following functions that compute whether a tree is valid
(see *note GRANULARITY:: for a discussion of the granularity form).

     (defun valid-tip (x)
       (declare (xargs :guard t))
       (or (eq x 'A)
           (eq x 'T)
           (eq x 'C)
           (eq x 'G)))

     (defun pvalid-tree (x depth)
       (declare (xargs :guard (natp depth)))
       (if (atom x)
           (valid-tip x)
         (pand (declare (granularity (< depth 10)))
               (pvalid-tree (car x) (1+ depth))
               (pvalid-tree (cdr x) (1+ depth)))))

We would like to stop execution as soon as any tip is found to be
invalid.  So, when computing the conjunction of terms by using pand,
once one of those terms evaluates to nil, the computations for the
other terms are aborted and the pand call returns nil.  By using pand,
we can in principle attain a speedup factor greater than the number of
available cores.

The concept of early termination also applies to por, except that early
termination occurs when an argument evaluates to non-nil.


File: acl2-doc-emacs.info,  Node: ERROR-TRIPLES-AND-PARALLELISM,  Next: GRANULARITY,  Prev: EARLY-TERMINATION,  Up: PARALLEL-PROGRAMMING

ERROR-TRIPLES-AND-PARALLELISM    how to avoid error triples in ACL2(p)

This documentation topic relates to the experimental extension of ACL2
supporting parallel execution and proof; see *note PARALLELISM::.

ACL2 supports the use of error triples in many features; e.g.,
computed-hints.  (For background on error triples, see *note
PROGRAMMING-WITH-STATE::.)  However, ACL2(p) does not support the use of
error triples in some of these features (e.g., computed-hints) while
waterfall-parallelism is enabled.

You may see an error message like the following when running ACL2(p)
with waterfall-parallelism enabled:

     ACL2 Error in ( THM ...):  Since we are translating a form in ACL2(p)
     intended to be executed with waterfall parallelism enabled, the form
     (MY-STATE-MODIFYING-COMPUTED-HINT ID STATE) was expected to represent
     an ordinary value, not an error triple (mv erp val state), as would
     be acceptable in a serial execution of ACL2.  Therefore, the form returning
     a tuple of the form (* * STATE) is an error.  See :DOC unsupported-
     waterfall-parallelism-features and :DOC error-triples-and-parallelism
     for further explanation.

In this particular example, the cause of the error was trying to use a
computed hint that returned state, which is not allowed when executing
the waterfall in parallel (see *note
UNSUPPORTED-WATERFALL-PARALLELISM-FEATURES:: for other related
information).

Often, the only reason users need to return state is so they can perform
some output during the proof process.  In this case, we suggest using
one of the state-free output functions, like cw or observation-cw.  If
the user is concerned about the interleaving of their output with other
output, these calls can be surrounded with the macro with-output-lock.

Another frequent reason users return state is so they can cause a soft
error and halt the proof process.  In this case, we suggest instead
calling er with the hard or hard? severity.  By using these mechanisms,
the user avoids modifying state, a requirement for much of the code
written in ACL2(p).

You may encounter other similar error messages when using
computed-hints, custom-keyword-hints, or override-hints.  Chances are
that you are somehow returning an error triple when an ordinary value
is needed.  If this turns out not to be the case, please let the ACL2
implementors know.


File: acl2-doc-emacs.info,  Node: GRANULARITY,  Next: PAND,  Prev: ERROR-TRIPLES-AND-PARALLELISM,  Up: PARALLEL-PROGRAMMING

GRANULARITY    limit the amount of parallelism

This documentation topic relates to the experimental extension of ACL2
supporting parallel execution and proof; see *note PARALLELISM::.

Some function calls are on arguments whose evaluation time is long
enough to warrant parallel execution, while others are not.  A
granularity form can be used to make appropriate restrictions on the
use of parallelism.

For example, consider the Fibonacci function.  Experiments have
suggested that execution time can be reduced if whenever the argument
is less than 27, a serial version of the Fibonacci function is called.
One way to utilize this information is to write two definitions of the
Fibonacci function, one serial and one parallel.

     (defun fib (x)
       (declare (xargs :guard (natp x)))
       (cond ((or (zp x) (<= x 0)) 0)
             ((= x 1) 1)
             (t (binary-+ (fib (- x 1))
                          (fib (- x 2))))))

     (defun pfib (x)
       (declare (xargs :guard (natp x)))
       (cond ((or (zp x) (<= x 0)) 0)
             ((= x 1) 1)
             ((< x 27) (binary-+ (fib (- x 1))
                                 (fib (- x 2))))
             (t (pargs (binary-+ (pfib (- x 1))
                                 (pfib (- x 2)))))))

We realize quickly that writing both of these function definitions is
cumbersome and redundant.  This problem can be avoided by using a
granularity declaration with a parallelism primitive.  This form ensures
that a call is parallelized only if resources are available and the
granularity form evaluates to a non-nil value at the time of the call.
Below is a definition of the Fibonacci function using a granularity
form.

     (defun pfib (x)
       (declare (xargs :guard (natp x)))
       (cond ((or (zp x) (<= x 0)) 0)
             ((= x 1) 1)
             (t (pargs (declare (granularity (>= x 27)))
                       (binary-+ (pfib (- x 1))
                                 (pfib (- x 2)))))))

A granularity form can reference an extra formal parameter that
describes the call depth of the function the user is parallelizing.
Consider for example the following parallel mergesort function, based
on Davis's Ordered Sets library.  It splits the data into symmetric
chunks for computation, so we increment the depth argument during the
recursive call on both the car and cdr.

     (include-book "finite-set-theory/osets/sets" :dir :system)
     (defun sets::pmergesort-exec (x depth)
       (declare (xargs :mode :program))
       (cond ((endp x) nil)
             ((endp (cdr x)) (sets::insert (car x) nil))
             (t (mv-let (part1 part2)
                        (sets::split-list x nil nil)
                        (pargs
                         (declare (granularity (< depth 2)))
                         (sets::union (sets::pmergesort-exec part1
                                                             (1+ depth))
                                      (sets::pmergesort-exec part2
                                                             (1+ depth))))))))

A less intrusive method (i.e., not requiring an extra formal parameter
like the depth argument just above), which however can be less
efficient, involves analyzing the data itself for structural
properties.  For example:

     (defun some-depth-exceeds (x n)
       (declare (xargs :guard (natp n)))
       (if (atom x)
           nil
         (if (zp n)
             t
           (or (some-depth-exceeds (car x) (1- n))
               (some-depth-exceeds (cdr x) (1- n))))))

     (defun valid-tip (x)
       (declare (xargs :guard t))
       (or (eq x 'A)
           (eq x 'T)
           (eq x 'C)
           (eq x 'G)))

     (defun pvalid-tree (x)
       (declare (xargs :guard t))
       (if (atom x)
           (valid-tip x)
         (pand (declare (granularity (some-depth-exceeds x 3)))
               (pvalid-tree (car x))
               (pvalid-tree (cdr x)))))

If you experiment with calls of pvalid-tree, you are likely to find that
the "speedup" it provides over a corresponding serial version is, in
fact, a slowdown!  The problem is likely that some-depth-exceeds is an
expensive function to run repeatedly.  Instead of the approach above,
it is often handy to add an extra formal parameter in order to allow
for more efficient granularity forms, as we have done above in the
definition of SETS::pmergesort-exec.


File: acl2-doc-emacs.info,  Node: PAND,  Next: PARALLEL-EXECUTION,  Prev: GRANULARITY,  Up: PARALLEL-PROGRAMMING

PAND    parallel, Boolean version of and

This documentation topic relates to the experimental extension of ACL2
supporting parallel execution and proof; see *note PARALLELISM::.

     Example Forms:
     (pand (subsetp-equal x y)
           (subsetp-equal y x))

     (pand (declare
            (granularity
             (and (> (length x) 500)
                  (> (length y) 500))))
            (subsetp-equal x y)
            (subsetp-equal y x))

     General Form:
     (pand (declare (granularity expr)) ; optional granularity declaration
           arg1 ... argN)

where N >= 0 and each argi and expr are arbitrary terms.

Pand evaluates its arguments in parallel.  It returns a Boolean result:
nil if any argument evaluates to nil, else t.  Note that pand always
returns a Boolean result, even though and can return a non-nil value
other than t, namely the value of its last argument.  (A moment's
reflection will make it clear that in order for por to parallelize
efficiently, it needs to return a Boolean value; so pand returns a
Boolean value for consistency with por.)

Another difference between pand and and is that for a call of pand,
even if an argument evaluates to nil, a subsequent argument may be
evaluated.  Consider the following example (where cw prints a string;
see *note CW::).

     (defun bar ()
       (pand (equal (make-list 100000) nil) ; evaluates to nil
             (cw "hello world~%")))

When (bar) is evaluated, the above arguments of pand can execute in
parallel, causing "hello world" to be printed to the terminal.  If we
had used and rather than pand, then since (equal (make-list 100000)
nil) evaluates to nil, the above call of cw would be avoided and no
such printing would take place.  Even with pand, such printing _might_
not take place, depending on resources, timing of thread creation, and
whether or not parallel execution is enabled (see *note
SET-PARALLEL-EXECUTION::).

Note that unlike the case for and, the definition of pand does not
provide (consp x) as a guard to (car x) in the call of pand below:

     (defun h (x)
       (declare (xargs :guard t))
       (pand (consp x) (equal (car x) 'foo)))

As a result, guard verification will fail for the above definition.  If
pand were replaced by and, then guard verification would succeed.

See *note PARALLELISM-TUTORIAL:: for another example.  Also see *note
PARALLELISM-AT-THE-TOP-LEVEL:: for restrictions on evaluating
parallelism primitives from within the ACL2 top-level loop.  Finally
see *note EARLY-TERMINATION:: to read how pand can offer more
efficiency than and by avoiding evaluation of some of its arguments.


File: acl2-doc-emacs.info,  Node: PARALLEL-EXECUTION,  Next: PARALLELISM-AT-THE-TOP-LEVEL,  Prev: PAND,  Up: PARALLEL-PROGRAMMING

PARALLEL-EXECUTION    for ACL2(p): configure parallel execution

See *note SET-PARALLEL-EXECUTION:: for how to configure parallel
execution for calls of plet, pargs, pand, por (but not spec-mv-let).


File: acl2-doc-emacs.info,  Node: PARALLELISM-AT-THE-TOP-LEVEL,  Next: PARALLELISM-PERFORMANCE,  Prev: PARALLEL-EXECUTION,  Up: PARALLEL-PROGRAMMING

PARALLELISM-AT-THE-TOP-LEVEL    parallel execution in the ACL2 top-level loop

This documentation topic relates to the experimental extension of ACL2
supporting parallel execution and proof; see *note PARALLELISM::.

Calls of parallelism primitives made explicitly in the ACL2 top-level
loop, as opposed to inside function bodies, will never cause parallel
execution.  Such calls will either execute with serial execution or
will cause an error; see *note SET-PARALLEL-EXECUTION::.  For a way
around this restriction, see *note TOP-LEVEL::.

Consider for example the following call of pargs in the ACL2 top-level
loop.  Instead of executing pargs, ACL2 macroexpands away this call,
leaving us with serial execution of the arguments to the cons call, or
else causes an error (see *note SET-PARALLEL-EXECUTION::).  If there is
no error, then

     (pargs (cons (expensive-fn-1 4) (expensive-fn-2 5)))

expands into:

     (cons (expensive-fn-1 4) (expensive-fn-2 5))

One trivial way to enable parallel execution of a form is to surround it
with a call to macro top-level.  Consider the following example.

     (top-level (pargs (cons (expensive-fn-1 4) (expensive-fn-2 5))))

Then in an executable image that supports parallel execution -- see
*note COMPILING-ACL2P:: for instructions on how to build such an
executable -- (expensive-fn-1 4) and (expensive-fn-2 5) can evaluate in
parallel.

A second way to enable parallel execution of a form is to place it
inside a function body.  For example, consider the following definition.

     (defun foo (x y)
       (pargs (cons (expensive-fn-1 x) (expensive-fn-2 y))))

Then in an executable image that supports parallel execution,
submission of the form (foo 4 5) can cause parallel execution of
(expensive-fn-1 4) and (expensive-fn-2 5).

Note that guards need not be verified in order to obtain parallel
execution.  The only restrictions on parallel execution are to use an
executable supporting it, to avoid calling parallelism primitives
directly in the top-level loop, to have sufficient resources
(especially, threads) available, and to avoid explicitly disabling
parallel execution (see *note SET-PARALLEL-EXECUTION::).


File: acl2-doc-emacs.info,  Node: PARALLELISM-PERFORMANCE,  Next: PARALLELISM-TUTORIAL,  Prev: PARALLELISM-AT-THE-TOP-LEVEL,  Up: PARALLEL-PROGRAMMING

PARALLELISM-PERFORMANCE    performance issues for parallel execution

This documentation topic relates to the experimental extension of ACL2
supporting parallel execution and proof; see *note PARALLELISM::.

See *note GRANULARITY:: for an important construct that limits the
spawning of parallel computations, which can be important when a
computation is too short-lived to warrant a separate thread.

There are times in which parallelism provides no speedup because of
garbage collection in the underlying Lisp implementation.  The
following example illustrates this phenomenon.  If you change the
granularity declaration so that the depth bound is 3, 4, or larger
instead of 2, you may still find no speedup.  In all cases you may find
that parallelism results in a significantly greater time spent in
garbage collection.

     (include-book "finite-set-theory/osets/sets" :dir :system)
     (defun sets::pmergesort-exec (x depth)
         (declare (xargs :mode :program))
         (cond ((endp x) nil)
               ((endp (cdr x)) (sets::insert (car x) nil))
               (t (mv-let (part1 part2)
                          (sets::split-list x nil nil)
                          (pargs
                           (declare (granularity (< depth 2)))
                           (sets::union (sets::pmergesort-exec part1
                                                               (1+ depth))
                                        (sets::pmergesort-exec part2
                                                               (1+ depth))))))))
     (defconst *x* (reverse (fromto 1 400000)))
     (time$ (length (sets::pmergesort-exec *x* 0)))
     (set-parallel-execution nil)
     (time$ (length (sets::pmergesort-exec *x* 0)))


File: acl2-doc-emacs.info,  Node: PARALLELISM-TUTORIAL,  Next: PARGS,  Prev: PARALLELISM-PERFORMANCE,  Up: PARALLEL-PROGRAMMING

PARALLELISM-TUTORIAL    a tutorial on how to use the parallelism library.

This documentation topic relates to the experimental extension of ACL2
supporting parallel execution and proof; see *note PARALLELISM::.

In this topic we introduce the ACL2 parallelism primitives using the
example of a doubly-recursive Fibonacci function, whose basic
definition is as follows.  See *note PARALLELISM:: for a very
high-level summary of the parallelism capability described here, and
see *note COMPILING-ACL2P:: for how to build an executable image that
supports parallel execution.  Here, we assume that such an executable
is being used.

Serial Fibonacci

     (defun fib (x)
       (declare (xargs :guard (natp x)))
       (cond ((or (zp x) (<= x 0)) 0)
             ((= x 1) 1)
             (t (+ (fib (- x 1)) (fib (- x 2))))))

Introducing Pargs

A simple way to introduce parallelism into this function definition is
to wrap the addition expression with a call of pargs, and the arguments
to the addition will be computed in parallel whenever resources are
available.  As a result, we end up with a very similar and thus
intuitive function definition.  Note that we replaced + by binary-+,
since pargs expects a function call, not a macro call.

     (defun pfib (x)
       (declare (xargs :guard (natp x)))
       (cond ((or (zp x) (<= x 0)) 0)
             ((= x 1) 1)
             (t (pargs (binary-+ (pfib (- x 1))
                                 (pfib (- x 2)))))))

Introducing the Granularity Problem

After you submit the above two versions of the Fibonacci function, test
them with the following forms.

     (time$ (fib 10))
     (time$ (pfib 10))

Now increase the argument by increments of 5 to 10 until you find your
curiosity satisfied or your patience wearing thin.  You can interrupt
evaluation if necessary and return to the ACL2 loop.  You will
immediately notice that you have not increased execution speed, at
least not by much, by introducing parallelism.

First, consider the computation of (pfib 4).  Assuming resources are
available, (pfib 4) will create a thread for computing (pfib 3) and
another thread for (pfib 2).  It is easy to imagine that setting up each
thread takes much longer than the entire computation of (fib 4).

Second, we must realize that if we have two threads available for
computing (fib 10), then the evaluation of (fib 8) will probably
complete before the evaluation of (fib 9).  Once (fib 8) finishes,
parallelism resources will become available for the next recursive call
made on behalf of (fib 9).  If for example that call is (fib 3), we
will waste a lot of cycles just handing work to the thread that does
this relatively small computation.  We need a way to ensure that
parallelism resources are only used on problems of a "large" size.
Ensuring that only "large" problems are spawned is called the
"granularity problem."

In summary: We want to tell ACL2 that it can evaluate the arguments of
pargs in parallel only when the parameter of pfib is greater than some
threshold.  Our tests using CCL have suggested that 27 is a reasonable
threshold.

Explicit Programming for the Granularity Problem

One way to avoid the granularity problem is to duplicate code as
follows.

     (defun pfib (x)
       (declare (xargs :guard (natp x)))
       (cond ((or (zp x) (<= x 0)) 0)
             ((= x 1) 1)
             (t (if (> x 27) ; the granularity test
                    (pargs (binary-+ (pfib (- x 1))
                                     (pfib (- x 2))))
                  (binary-+ (pfib (- x 1))
                            (pfib (- x 2)))))))

Duplicating code is fundamentally a bad design principle, because it can
double the work for future maintenance.  A "granularity form" is an
expression

     (declare (granularity <form>))

that can allow threads to be spawned (without duplicating code)
whenever the evaluation of <form> results in a non-nil value.  It may
be placed inside any call of a parallelism primitive, in a position
documentated separately for each primitive.  Here is a definition of
pfib using this feature for a call of the parallelism primitive pargs.

     (defun pfib (x)
       (declare (xargs :guard (natp x)))
       (cond ((or (zp x) (<= x 0)) 0)
             ((= x 1) 1)
             (t (pargs
                 (declare (granularity (> x 27)))
                 (binary-+ (pfib (- x 1))
                           (pfib (- x 2)))))))

Test each version as follows (or substitute your own natural number for
33).

       (time$ (fib 33))
       (time$ (pfib 33))

Another Granularity Issue Related to Thread Limitations

Our implementation of parallelism primitives has the property that once
a thread is assigned a computation, that assignment stays in effect
until the computation is complete.  In particular, if a thread
encounters a parallelism primitive that spawns child threads, the
parent thread stays assigned, waiting until the child computations
complete before it can continue its own computation.  In the meantime,
the parent thread reduces the number of additional threads that Lisp
can provide by 1, rather than being reassigned to do other work.

How can this lack of reassignment affect the user?  Consider, for
example, the application of a recursive function to a long list.
Imagine that this function is written so that the body contains a
recursive call, for example as (pargs (process (car x)) (recur (cdr
x))).  Each such pargs call that spawns child work must wait for its
children, one of which is the work of evaluating (recur (cdr x)), to
complete.  There is an ACL2 limit on how much pending work can be in
the system, limiting the number of pargs calls that can result in
parallel execution.  For example, if the ACL2 limit is k and each call
of pargs actually spawns threads for evaluating  its arguments, then
after k cdrs there will be no further parallel execution.

Possible solutions may include reworking of algorithms (for example to
be tree-based rather than list-based) or using appropriate granularity
forms.  We hope that future implementations will allow thread
"re-deployment" in order to mitigate this problem.  This problem
applies to plet, pargs, pand, por, and spec-mv-let.

Introducing Plet

We can use a let binding to compute the recursive calls of fib and then
add the bound variables together, as follows.

     (defun fib (x)
       (declare (xargs :guard (natp x)))
       (cond ((or (zp x) (<= x 0)) 0)
             ((= x 1) 1)
             (t (let ((a (fib (- x 1)))
                      (b (fib (- x 2))))
                  (+ a b)))))

By using the parallelism primitive plet, we can introduce parallelism
much as we did using pargs, with an optional granularity form, as
follows.

     (defun pfib (x)
       (declare (xargs :guard (natp x)))
       (cond ((or (zp x) (<= x 0)) 0)
             ((= x 1) 1)
             (t (plet
                 (declare (granularity (> x 27)))
                 ((a (pfib (- x 1)))
                  (b (pfib (- x 2))))
                 (+ a b)))))

Notice that this time, we were able to use + rather than being forced to
use binary-+.  Unlike pargs, which expects a function call (not a macro
call), plet allows macros at the top level of its body.

Introducing Pand (By Way of a Tree Validation Example)

Consider "genetic trees" that contains leaves of DNA elements, in the
sense that each tip is one of the symbols A, G, C, or T.  First we
define the function valid-tip which recognizes whether a tip contains
one of these symbols.

     (defun valid-tip (tip)
       (declare (xargs :guard t))
       (or (eq tip 'A)
           (eq tip 'G)
           (eq tip 'C)
           (eq tip 'T)))

Now we define a function that traverses the tree, checking that every
tip is valid.

     (defun valid-tree-serial (tree)
       (declare (xargs :guard t))
       (if (atom tree)
           (valid-tip tree)
         (and (valid-tree-serial (car tree))
              (valid-tree-serial (cdr tree)))))

We also define a parallel version.

     (defun valid-tree-parallel (tree)
       (declare (xargs :guard t))
       (if (atom tree)
           (valid-tip tree)
         (pand (valid-tree-parallel (car tree))
               (valid-tree-parallel (cdr tree)))))

Before we can time the functions, we need to create test trees.  We have
found that test trees need to be approximately 1 gigabyte before we
clearly see speedup, and we make them asymmetric to demonstrate the
ability of our implementation to adapt to asymmetric data.  We can
create the trees with the execution of the following forms.

     (defun make-valid-binary-tree (x)
       (declare (xargs :mode :program))
       (if (< x 0)
           (cons (cons 'C 'G) (cons 'A 'T))
         (cons (make-valid-binary-tree (- x 2)) ; 2 to make asymmetric
               (make-valid-binary-tree (- x 1)))))

     (defconst *valid-tree* (make-valid-binary-tree 30)) ; takes awhile
     (defconst *invalid-tree* (cons *valid-tree* nil)) ; nil is invalid tip

We can time our functions with the forms:

     (time$ (valid-tree-serial *valid-tree*))
     (time$ (valid-tree-parallel *valid-tree*))

Unfortunately, the serial version runs faster than the parallelism
version; however, there is more to this story.

Demonstrating Early Termination with an Invalid Tree

Now observe this magic:

     (time$ (valid-tree-serial   *invalid-tree*))
     (time$ (valid-tree-parallel *invalid-tree*))

The serial version took awhile, while the parallel version finished
almost immediately.  The test for validation was split into testing the
car and the cdr of the *invalid-tree* root, and since the cdr was equal
to nil, its test returned immediately.  This immediate return quickly
interrupted the computation associated with the car, and returned the
result.

Granularity with Pand

We can also define a parallel version with a granularity form:

     (defun valid-tree-parallel (tree depth)
       (declare (xargs :guard (natp depth)))
       (if (atom tree)
           (valid-tip tree)
         (pand
          (declare (granularity (< depth 5)))
          (valid-tree-parallel (car tree) (1+ depth))
          (valid-tree-parallel (cdr tree) (1+ depth)))))

We can test this form by executing our previous forms.  You will
probably find some speedup on a machine with several cores available,
but more speedup can likely be obtained with an expensive test on the
leaves in place of valid-tip.

     (time$ (valid-tree-serial   *valid-tree*))
     (time$ (valid-tree-parallel *valid-tree* 0))

Introducing Por

Por can be used in the same way as pand, but with early termination
occurring when an argument evaluates to a non-nil value, in which case
the value returned is t.  Finally, por also supports the use of a
granularity form.


File: acl2-doc-emacs.info,  Node: PARGS,  Next: PLET,  Prev: PARALLELISM-TUTORIAL,  Up: PARALLEL-PROGRAMMING

PARGS    parallel evaluation of arguments in a function call

This documentation topic relates to the experimental extension of ACL2
supporting parallel execution and proof; see *note PARALLELISM::.

     Example Forms:
     (pargs (binary-+ (fibonacci (- x 1)) (fibonacci (- x 2))))

     (pargs (declare (granularity (> x 35)))
            (binary-+ (fibonacci (- x 1)) (fibonacci (- x 2))))

     General Form:
     (pargs (declare (granularity expr)) ; optional granularity declaration
            (f arg1 ... argN))

where N >= 0 and each argi and expr are arbitrary terms.  Logically,
pargs is just the identity macro, in the sense that the above forms can
logically be replaced by (f arg1 ... argN).  However, this pargs form
may parallelize the evaluation of arguments arg1 through argN before
applying function f to those results.  If the above granularity
declaration is present, then its expression (expr above) is first
evaluated, and if the result is nil, then such parallelism is avoided.
Even if parallelism is not thus avoided, parallelism may be limited by
available resources.

Since macros can change expressions in unexpected ways, it is illegal
to call pargs on a form that is a macro call.  To parallelize
computation of arguments to a macro, see *note PLET::.

See *note PARALLELISM-AT-THE-TOP-LEVEL:: for restrictions on evaluating
parallelism primitives from within the ACL2 top-level loop.


File: acl2-doc-emacs.info,  Node: PLET,  Next: POR,  Prev: PARGS,  Up: PARALLEL-PROGRAMMING

PLET    parallel version of let

This documentation topic relates to the experimental extension of ACL2
supporting parallel execution and proof; see *note PARALLELISM::.

     Example Forms:
     (plet ((a (fibonacci (- x 1)))
            (b (fibonacci (- x 2))))
           (+ a b))

     (plet (declare (granularity (> x 35)))
           ((a (fibonacci (- x 1)))
            (b (fibonacci (- x 2))))
           (+ a b))

     General Form:
     (plet (declare (granularity expr)) ; optional granularity declaration
           ((var1 val1)
            ...
            (varN valN))
           (declare ...) ... (declare ...) ; optional declarations
           body)

The syntax of plet is identical to the syntax of let, except that plet
permits an optional granularity declaration in the first argument
position; see *note GRANULARITY::.  In the logic a call of plet
macroexpands to the corresponding call of let, where the granularity
declaration (if any) is dropped.

Plet cause the evaluation of each vali above to be done in parallel
before processing the body.  If the above granularity declaration is
present, then its expression (expr above) is first evaluated, and if the
result is nil, then such parallelism is avoided.  Even if parallelism is
not thus avoided, parallelism may be limited by available resources.

See *note PARALLELISM-AT-THE-TOP-LEVEL:: for restrictions on evaluating
parallelism primitives from within the ACL2 top-level loop.


File: acl2-doc-emacs.info,  Node: POR,  Next: SPEC-MV-LET,  Prev: PLET,  Up: PARALLEL-PROGRAMMING

POR    parallel, Boolean version of or

This documentation topic relates to the experimental extension of ACL2
supporting parallel execution and proof; see *note PARALLELISM::.

     Example Forms:
     (por (subsetp-equal x y)
          (subsetp-equal y x))

     (por (declare
           (granularity
            (and (> (length x) 500)
                 (> (length y) 500))))
           (subsetp-equal x y)
           (subsetp-equal y x))

     General Form:
     (por (declare (granularity expr)) ; optional granularity declaration
          arg1 ... argN)

where N >= 0 and each argi and expr are arbitrary terms.

Por evaluates its arguments in parallel.  It returns a Boolean result:
t if any argument evaluates to non-nil, else nil.  Note that while or
returns the first non-nil value from evaluating its arguments
left-to-right (if any such value is not nil) por always returns a
Boolean result, in support of efficiency (see *note EARLY-TERMINATION::)
in light of the nondeterministic order in which argument values are
returned.

Another difference between por and or is that for a call of por, even
if the an argument's value is not nil, a subsequent argument may be
evaluated.  See *note PAND:: for a discussion of the analogous property
of pand.  In particular, guards generated from calls of por may not
assume for an argument that the preceding arguments evaluated to nil.

See *note PARALLELISM-TUTORIAL:: for another example.  Also see *note
PARALLELISM-AT-THE-TOP-LEVEL:: for restrictions on evaluating
parallelism primitives from within the ACL2 top-level loop.  Finally
see *note EARLY-TERMINATION:: to read how por can offer more efficiency
than or by avoiding evaluation of some of its arguments.


File: acl2-doc-emacs.info,  Node: SPEC-MV-LET,  Next: WITH-OUTPUT-LOCK,  Prev: POR,  Up: PARALLEL-PROGRAMMING

SPEC-MV-LET    modification of mv-let supporting speculative and parallel execution

This documentation topic relates to the experimental extension of ACL2
supporting parallel execution and proof; see *note PARALLELISM::.

     Example Form:
     (defun pfib-with-step-count (x)
       (declare (xargs :mode :program))
       (if (or (zp x) (< x 33))
           (fib-with-step-count x)
         (spec-mv-let
          (a cnt1)
          (pfib-with-step-count (- x 1))
          (mv-let (b cnt2)
                  (pfib-with-step-count (- x 2))
                  (if t
                      (mv (+ a b)
                          (+ 1 cnt1 cnt2))
                    (mv "speculative result is always needed"
                        -1))))))

     General Form:
     (spec-mv-let
      (v1 ... vn)  ; bind distinct variables
      <spec>       ; evaluate speculatively; return n values
      (mv-let      ; or, use mv?-let if k=1 below
       (w1 ... wk) ; bind distinct variables
       <eager>     ; evaluate eagerly
       (if <test>  ; use results from <spec> if true
           <typical-case> ; may mention v1 ... vn
         <abort-case>)))  ; does not mention v1 ... vn

Our design of spec-mv-let is guided by its use in ACL2 source code to
parallelize part of ACL2's proof process, in the experimental parallel
extension of ACL2.  The user can think of spec-mv-let as a speculative
version of mv-let.  (In ordinary ACL2, the semantics agree with this
description but without speculative or parallel execution.)

Evaluation of the above general form proceeds as suggested by the
comments.  First, <spec> is executed speculatively.  Control then
passes immediately to the mv-let call, without waiting for the result
of evaluating <spec>.  The variables (w1 ... wk) are bound to the
result of evaluating <eager>, and then <test> is evaluated.  If the
value of <test> is true, then the values of (v1 ... vn) are needed, and
<typical-case> blocks until they are available.  If the value of <test>
is false, then the values of (v1 ... vn) are not needed, and the
evaluation of <spec> may be aborted.

The calls to mv-let and to if displayed above in the General Form are
an essential part of the design of spec-mv-let, and are thus required.

The following definition of fib-with-step-count completes the example
above:

     (defun fib-with-step-count (x)
     (declare (xargs :mode :program))
     (cond ((<= x 0)
            (mv 0 1))
           ((= x 1) (mv 1 1))
           (t (mv-let (a cnt1)
                      (fib-with-step-count (- x 1))
                      (mv-let (b cnt2)
                              (fib-with-step-count (- x 2))
                              (mv (+ a b)
                                  (+ 1 cnt1 cnt2)))))))


File: acl2-doc-emacs.info,  Node: WITH-OUTPUT-LOCK,  Prev: SPEC-MV-LET,  Up: PARALLEL-PROGRAMMING

WITH-OUTPUT-LOCK    provides a mutual-exclusion mechanism for performing output in parallel

This documentation topic relates to an experimental extension of ACL2,
ACL2(p), created initially by David L. Rager.  See *note
COMPILING-ACL2P:: for how to build an executable image that supports
parallel execution.  Also see community books directory books/parallel/
for examples.

One may wish to perform output while executing code in parallel.  If
threads are allowed to print concurrently, the output will be
interleaved and often unreadable.  To avoid this, the user can surround
forms that perform output with the with-output-lock macro.

Take the following definition of pfib as an example.

     (defun pfib (x)
       (declare (xargs :guard (natp x)))
       (cond ((mbe :logic (or (zp x) (<= x 0))
                   :exec (<= x 0))
              0)
             ((= x 1) 1)
             (t (plet (declare (granularity t))
                      ((a (prog2$ (cw "Computing pfib ~x0~%" (- x 1))
                                  (pfib (- x 1))))
                       (b (prog2$ (cw "Computing pfib ~x0~%" (- x 2))
                                  (pfib (- x 2)))))
                      (+ a b)))))

With parallel-execution enabled, a call of (pfib 5)results in
non-deterministically interleaved output, for example as follows.

     ACL2 !>(pfib 5)
     CComputing pfib 4
     omputing pfib 3
     ComCpuotmipnugt ipnfgi bp fib3
     2
     Computing pCfiobm put2i
     ng pfib 1
     Computing pfib Co1mp
     uting pfib 0
     CCoommppuuttiinngg  ppffiibb  12

     ComCpuotmipnugt ipnfgi bp fib1
     0
     CoCmopmuptuitnign gp fpifbi b 1
     0
     5
     ACL2 !>

If the user instead surrounds the calls to cw with the macro
with-output-lock, as in the following session, the output will no longer
be interleaved.

     ACL2 !>
     (defun pfib (x)
       (declare (xargs :guard (natp x)))
       (cond ((mbe :logic (or (zp x) (<= x 0))
                   :exec (<= x 0))
              0)
             ((= x 1) 1)
             (t (plet (declare (granularity t))
                      ((a (prog2$ (with-output-lock
                                   (cw "Computing pfib ~x0~%" (- x 1)))
                                  (pfib (- x 1))))
                       (b (prog2$ (with-output-lock
                                   (cw "Computing pfib ~x0~%" (- x 2)))
                                  (pfib (- x 2)))))
                      (+ a b)))))

     <snip>

     ACL2 !>(pfib 5)
     Computing pfib 4
     Computing pfib 3
     Computing pfib 3
     Computing pfib 2
     Computing pfib 2
     Computing pfib 1
     Computing pfib 2
     Computing pfib 1
     Computing pfib 1
     Computing pfib 0
     Computing pfib 1
     Computing pfib 0
     Computing pfib 1
     Computing pfib 0
     5
     ACL2 !>


File: acl2-doc-emacs.info,  Node: PARALLEL-PROOF,  Next: UNSUPPORTED-PARALLELISM-FEATURES,  Prev: PARALLEL-PROGRAMMING,  Up: PARALLELISM

PARALLEL-PROOF    parallel proof in ACL2(p)

Here we document support for parallel proof in ACL2(p), an experimental
extension of ACL2; also see *note PARALLELISM::, and for parallel
programming in particular, see *note PARALLEL-PROGRAMMING::.

* Menu:

* ACL2P-KEY-CHECKPOINTS:: key checkpoints in ACL2(p)

* DEFAULT-TOTAL-PARALLELISM-WORK-LIMIT:: for ACL2(p): returns the default value for global total-parallelism-work-limit

* PARALLEL-PUSHING-OF-SUBGOALS-FOR-INDUCTION:: consequences of how parallelized proofs of subgoals are pushed for induction

* UNSUPPORTED-WATERFALL-PARALLELISM-FEATURES:: proof features not supported with waterfall-parallelism enabled

* WATERFALL-PARALLELISM:: for ACL2(p): configuring the parallel execution of the waterfall

* WATERFALL-PRINTING:: for ACL2(p): configuring the printing within the parallelized waterfall


Related topics other than immediate subtopics:
* SET-TOTAL-PARALLELISM-WORK-LIMIT:: for ACL2(p): set thread limit for parallelism primitives

* SET-TOTAL-PARALLELISM-WORK-LIMIT-ERROR:: for ACL2(p): control the action taken when the thread limit is exceeded

* SET-WATERFALL-PARALLELISM:: for ACL2(p): configuring the parallel execution of the waterfall

* SET-WATERFALL-PARALLELISM-HACKS-ENABLED:: for ACL2(p): enable waterfall-parallelism hacks

* SET-WATERFALL-PARALLELISM-HACKS-ENABLED!:: for ACL2(p): enabling waterfall parallelism hacks

* SET-WATERFALL-PRINTING:: for ACL2(p): configuring the printing that occurs within the parallelized waterfall


File: acl2-doc-emacs.info,  Node: ACL2P-KEY-CHECKPOINTS,  Next: DEFAULT-TOTAL-PARALLELISM-WORK-LIMIT,  Prev: PARALLEL-PROOF,  Up: PARALLEL-PROOF

ACL2P-KEY-CHECKPOINTS    key checkpoints in ACL2(p)

This documentation topic relates to the experimental extension of ACL2
supporting parallel execution and proof; see *note PARALLELISM::.

For printing output, the parallel version of the waterfall follows the
precedent of gag-mode.  The idea behind gag mode is to print only the
subgoals most relevant to debugging a failed proof attempt.  These
subgoals are called 'key checkpoints' (see *note SET-GAG-MODE:: for the
definition of "key" and "checkpoint"), and we restrict the default
output mode for the parallel version of the waterfall to printing
checkpoints similar to these key checkpoints.

* Menu:


Related topics other than immediate subtopics:
* SET-WATERFALL-PRINTING:: for ACL2(p): configuring the printing that occurs within the parallelized waterfall

As of this writing, we are aware of exactly one discrepancy between gag
mode's key checkpoints and the parallel version of the waterfall's
checkpoints.  This discrepancy occurs when using "by" hints (see *note
HINTS::).  As an example, take the following form, which attempts to
prove a non-theorem:

     (thm (equal (append x y z) (append z (append y x)))
          :hints (("Subgoal *1/2'''" :by nil)))

With waterfall parallelism enabled, Subgoal *1/2" will be printed as a
key checkpoint.  This is different from using gag-mode while running
the serial version of the waterfall, which skips printing the subgoal
as a checkpoint.

For those familiar with the ACL2 waterfall, we note that that the
parallel version of the waterfall prints key checkpoints that are
unproved in the following sense: a subgoal is a key checkpoint if it
leads, in the current call of the waterfall, to a goal that is pushed
for induction.


File: acl2-doc-emacs.info,  Node: DEFAULT-TOTAL-PARALLELISM-WORK-LIMIT,  Next: PARALLEL-PUSHING-OF-SUBGOALS-FOR-INDUCTION,  Prev: ACL2P-KEY-CHECKPOINTS,  Up: PARALLEL-PROOF

DEFAULT-TOTAL-PARALLELISM-WORK-LIMIT    for ACL2(p): returns the default value for global total-parallelism-work-limit

See *note SET-TOTAL-PARALLELISM-WORK-LIMIT::.


File: acl2-doc-emacs.info,  Node: PARALLEL-PUSHING-OF-SUBGOALS-FOR-INDUCTION,  Next: UNSUPPORTED-WATERFALL-PARALLELISM-FEATURES,  Prev: DEFAULT-TOTAL-PARALLELISM-WORK-LIMIT,  Up: PARALLEL-PROOF

PARALLEL-PUSHING-OF-SUBGOALS-FOR-INDUCTION    consequences of how parallelized proofs of subgoals are pushed for induction

This documentation topic relates to the experimental extension of ACL2
supporting parallel execution and proof; see *note PARALLELISM::.

The following discussion, concerning the naming of subgoals pushed for
proof by induction and the timeliness of aborting when two or more
goals are pushed for proof by induction, only applies when waterfall
parallelism is enabled (see *note SET-WATERFALL-PARALLELISM::).

When two sibling subgoals (e.g. 4.5 and 4.6) both push goals to be
proved by induction (e.g., 4.6 pushes *1 and 4.5 pushes *2), a name is
assigned to the second pushed subgoal (e.g., *2) as if the first push
hasn't happened (e.g., *2 is mistakenly called *1).  In such a case, we
say what the name _could_ be.  The following non-theorem illustrates
how this works.

     (set-waterfall-parallelism :full)
     (thm (equal (append (car (cons x x)) y z) (append x x y)))

There is another consequence of the way the parallelized waterfall
pushes subgoals for proof by induction.  Without waterfall parallelism
enabled, ACL2 sometimes decides to abort instead of pushing a goal for
later proof by induction, preferring instead to induct on the original
conjecture.  But with waterfall parallelism enabled, the prover no
longer necessarily immediately aborts to prove the original conjecture.
Suppose for example that sibling subgoals, Subgoal 4.6 and Subgoal 4.5,
each push a subgoal for induction.  If the waterfall is performing the
proof of each of these subgoals in parallel, the proof will no longer
abort immediately after the second push occurs, that is at Subgoal 4.5.
As a result, the prover will continue through Subgoal 4.4, Subgoal 4.3,
and beyond.  It is not until the results of combining the proof results
of Subgoal 4.6 with the results from the remaining sibling subgoals
(4.5, 4.4, and so on), that the proof attempt will abort and revert to
prove the original conjecture by induction.  This example illustrates
behavior that is rather like the case that :otf-flg is t, in the sense
that the abort does not happen immediately, but also rather like the
case that :otf-flg is nil, in the sense that the abort does occur
before getting to Subgoal 3.


File: acl2-doc-emacs.info,  Node: UNSUPPORTED-WATERFALL-PARALLELISM-FEATURES,  Next: WATERFALL-PARALLELISM,  Prev: PARALLEL-PUSHING-OF-SUBGOALS-FOR-INDUCTION,  Up: PARALLEL-PROOF

UNSUPPORTED-WATERFALL-PARALLELISM-FEATURES    proof features not supported with waterfall-parallelism enabled

For a general introduction to ACL2(p), an experimental extension of
ACL2 that supports parallel execution and proof, see *note
PARALLELISM::.  Please note that although this extension is usable and,
we hope, robust in its behavior, there are still known issues to
address beyond those listed explicitly below.  While we expect ACL2(p)
to perform correctly, it may never have the same level of attention to
correctness as is given to ACL2; see *note PARALLELISM::, specifically
the "IMPORTANT NOTE" there.

Below we list proof features of ACL2 that are not yet supported when
parallel execution is enabled for the primary ACL2 proof process,
generally known as "the waterfall", typically by calling
set-waterfall-parallelism.

Please note that this topic is limited to the case that such waterfall
parallelism is enabled.  We believe that all ACL2 proof procedures are
supported when waterfall parallelism is disabled, even in executables
that support parallelism (see *note COMPILING-ACL2P::).

Without a trust tag (see *note DEFTTAG::): We support clause-processors,
computed-hints, and custom-keyword-hints that do not modify state, but
we do not permit override-hints, regardless of whether they modify
state.  With a trust tag, the user can use clause-processors that
modify state and can also use override-hints (see *note
SET-WATERFALL-PARALLELISM-HACKS-ENABLED:: for a convenient mechanism for
adding a trust tag).  See *note ERROR-TRIPLES-AND-PARALLELISM:: for a
discussion of how to avoid modifying state in such situations.
Regardless of whether a trust tag is active: We do not support checkers
of custom-keyword-hints to be anything but the default checker.

GNU Make versions 3.81 and 3.82 formerly caused a lot of problems
(version 3.80 somewhat less so), at least on Linux, when certifying
books with ACL2 built on a host Lisp of CCL using `make'.  CCL was
updated around March 23, 2011 to fix this problem, so if you get
segfaults (for example) with CCL, try updating your CCL installation.

Book certification should generally work but may present some issues,
including the following.

     o The standard `make'-based process for book certification will
     not use waterfall-parallelism, which is disabled by default (even
     when compiling-acl2p by using the ACL2_PAR flag).  See *note
     BOOKS-CERTIFICATION:: and see *note BOOKS-CERTIFICATION-CLASSIC::,
     which explain that acl2-customization files are ignored during
     that process unless specified explicitly on the command line or in
     the environment.

     o A book certified with ACL2(p) might subsequently cause an error
     when included with ACL2.  As of this writing, however, we have
     only seen this for a book in which deftheory-static is used.

     o In general, ACL2(p) is primarily intended to support more rapid
     interactive development.  While we are unaware of an unsoundness
     likely to affect an ACL2(p) user, we suggest using ACL2 for final
     book certification, rather than ACL2(p), to lower the risk of
     unsound book certification.


Proof output can contain repeated printing of the same subgoal name.

Gag-mode isn't officially supported, although it has proved helpful to
use ACL2(p) in conjunction with (set-gag-mode t) (because this setting
suppresses the output that occurs outside the waterfall).  This being
said, ACL2(p) also prints key checkpoints (for example see *note
INTRODUCTION-TO-KEY-CHECKPOINTS::), but with a notion of "key
checkpoint" that does not take into account whether the goal is later
proved by induction.  See *note ACL2P-KEY-CHECKPOINTS:: for further
explanation of these key checkpoints.  Note that pso is also not
supported.

The :brr utility is not supported.

The accumulated-persistence utility is not supported.

Tracking for forward-chaining-reports is not supported (see *note
SET-FC-CRITERIA::).

Time limits (see *note WITH-PROVER-TIME-LIMIT::) aren't supported.

The timing information printed at the end of a proof attempt, which is
intended to represent cpu time (not wall-clock time), may be somewhat
inaccurate when waterfall-parallelism is non-nil.  Consider using time$
to obtain timing information.

The use of wormholes is not recommended, as there may be race
conditions.

Output specific to :OR hints is disabled.

Proof trees are likely not to work as originally designed.

The use of set-inhibit-output-lst may not fully inhibit proof output.

Reporting of splitter rules is currently unsupported when
waterfall-parallelism is on.

Interrupting a proof attempt is not yet properly supported.  At a
minimum, interrupts are trickier with waterfall parallelism enabled.
For one, the user typically needs to issue the interrupt twice before
the proof attempt is actually interrupted.  Additionally, on rare
occasions the theorem is registered as proved, even though the prover
did not finish the proof.  If this occurs, issue a :u (see *note UBT::)
and you will likely be at a stable state.

Also with regards to interrupting a proof attempt, sometimes the user
may need to issue a :q and lp to reset properly the parallelism
implementation to a stable state.  The primary symptom that the user is
experiencing this issue is that threads will continue to compute in the
background, even though there should be no proof attempt in progress.
The user can observe this symptom by examining the CPU utilization of
their ACL2 process, for example on Linux/Unix with the shell process
top.  Lisp usage greater than a few percent is indicative of this
problem.

Because of how ACL2 arrays are designed, the user may find that, in
practice, ACL2 arrays work (but perhaps with some slow-array-warning
messages).  However, we are aware of race conditions that can cause
problems.

Instead of dynamically monitoring rewrites, dmr instead dynamically
outputs information helpful for debugging the performance of proof
parallelism.  The instructions concerning how to see this debugging
information are the same as the instructions for enabling dmr mode.

If you are working with LispWorks 6.0 or 6.0.1, then you may see
messages about misaligned conses.  The state of the system may be
corrupted after such a message has been printed.  This LispWorks bug is
fixed in LispWorks 6.1.

The waterfall parallelism mode :resource-and-timing-based is not fully
supported when the host Lisp is other than CCL.  It may work, but we
have not attempted to address a potential race condition.

Proof output for splitter rules (see *note SPLITTER::) is currently
unsupported when waterfall-parallelism is enabled.

(Comment for ACL2(h) users; see *note HONS-AND-MEMOIZATION::.)
Memoization may not work as intended when executing in parallel
(including the waterfall).  In an effort to be helpful to the user, the
functions automatically memoized by ACL2(h) are unmemoized when setting
waterfall parallelism to anything but nil.  Those exact functions are
again memoized once waterfall parallelism is disabled.  Additionally,
any functions memoized within the ACL2 loop (by a call of memoize) are
also unmemoized when enabling waterfall parallelism and once again
memoized when disabling waterfall parallelism.  This is implemented by
returning the memoization state to what it was before enabling
waterfall parallelism.  As such, the user should be aware that any
changes made to the memoization state while waterfall parallelism is
enabled will be lost once waterfall parallelism is disabled.


File: acl2-doc-emacs.info,  Node: WATERFALL-PARALLELISM,  Next: WATERFALL-PRINTING,  Prev: UNSUPPORTED-WATERFALL-PARALLELISM-FEATURES,  Up: PARALLEL-PROOF

WATERFALL-PARALLELISM    for ACL2(p): configuring the parallel execution of the waterfall

See *note SET-WATERFALL-PARALLELISM::.


File: acl2-doc-emacs.info,  Node: WATERFALL-PRINTING,  Prev: WATERFALL-PARALLELISM,  Up: PARALLEL-PROOF

WATERFALL-PRINTING    for ACL2(p): configuring the printing within the parallelized waterfall

See *note SET-WATERFALL-PRINTING::.


File: acl2-doc-emacs.info,  Node: UNSUPPORTED-PARALLELISM-FEATURES,  Next: WATERFALL-PARALLELISM-FOR-BOOK-CERTIFICATION,  Prev: PARALLEL-PROOF,  Up: PARALLELISM

UNSUPPORTED-PARALLELISM-FEATURES    ACL2 features not supported in ACL2(p)

This documentation topic relates to the experimental extension of ACL2
supporting parallel execution and proof; see *note PARALLELISM::.  See
*note PARALLELISM-TUTORIAL:: for an introduction to parallel
programming in ACL2.

For proof features of ACL2 that are not yet supported when parallel
execution is enabled for the primary ACL2 proof process, generally
known as "the waterfall", see *note
UNSUPPORTED-WATERFALL-PARALLELISM-FEATURES::.

Please note that this topic discusses ACL2 features that are disabled
when using ACL2(p) (see *note COMPILING-ACL2P::).  These features are
disabled regardless of whether waterfall parallelism is enabled.

Calls of observation-cw simply convert to calls of cw, so suppressing
observations (see *note SET-INHIBIT-OUTPUT-LST::) will not suppress
these messages.

Memoization is not supported when executing in parallel.  See *note
UNSUPPORTED-WATERFALL-PARALLELISM-FEATURES:: for memoization details
related to waterfall parallelism.

Since, as of April 2012, garbage collection is inherently sequential,
ACL2(p) minimizes the use of garbage collection by setting a high
garbage collection threshold.  As a result, ACL2(p) is not expected to
perform well on machines with less memory than this threshold (1
gigabyte, as of April 2012).

In CCL, the underlying parallel execution engine is tuned for the
number of CPU cores (or hardware threads) actually available in the
machine.  SBCL and LispWorks are tuned for a machine with 16 CPU cores.

CCL is considered to be the "flagship Lisp" for parallel execution in
ACL2.  The SBCL and LispWorks implementations are thought to be
generally stable.  However, due to their relatively less common use,
the SBCL and LispWorks implementations are likely less robust than the
CCL implementation.

The time-tracker utility is a no-op for ACL2(p).


File: acl2-doc-emacs.info,  Node: WATERFALL-PARALLELISM-FOR-BOOK-CERTIFICATION,  Prev: UNSUPPORTED-PARALLELISM-FEATURES,  Up: PARALLELISM

WATERFALL-PARALLELISM-FOR-BOOK-CERTIFICATION    for ACL2(p): using waterfall parallelism during book certification

This documentation topic relates to the experimental extension of ACL2
supporting parallel execution and proof; see *note PARALLELISM::.

There are books whose certification can be sped up significantly by
using waterfall parallelism.  (See *note PARALLELISM::, including the
caveat in its "IMPORTANT NOTE".)  One such example in the ACL2
community books is models/jvm/m5/apprentice.lisp, which is typically
excluded from regressions because of how long it takes to certify.  In
order to use waterfall parallelism during certification of a book
<book-name>.lisp using `make' (see *note BOOKS-CERTIFICATION:: and see
*note BOOKS-CERTIFICATION-CLASSIC::), we recommend creating a file
<book-name>.acl2 that includes the following forms.

     #+acl2-par
     (set-waterfall-parallelism t)

     (certify-book <book-name> ? t) ; other arguments may be preferable

Note that there are books that will not certify when
waterfall-parallelism is enabled.  See file
acl2-customization-files/README for more information, including how to
certify essentially all books using waterfall parallelism.


File: acl2-doc-emacs.info,  Node: PROGRAMMING,  Next: PROOF-CHECKER,  Prev: PARALLELISM,  Up: Top

PROGRAMMING    programming in ACL2

This documentation topic is a parent topic under which we include
documentation topics for built-in functions, macros, and special forms
(see *note ACL2-BUILT-INS::) as well as topics for notions important to
programming with ACL2.  If you don't find what you're looking for, see
the Index or see individual topics that may be more directly
appropriate; for example, see *note EVENTS:: for top-level event
constructorsr like defun.

* Menu:

* ACL2-BUILT-INS:: built-in ACL2 functions

* ACL2-USER:: a package the ACL2 user may prefer

* ARRAYS:: an introduction to ACL2 arrays

* COMPILATION:: compiling ACL2 functions

* DECLARE:: declarations

* EQUALITY-VARIANTS:: versions of a function using different equality tests

* IGNORABLE:: See *note DECLARE::.

* IGNORE:: See *note DECLARE::.

* IRRELEVANT-FORMALS:: formals that are used but only insignificantly

* OPTIMIZE:: See *note DECLARE::.

* REDEFINING-PROGRAMS:: an explanation of why we restrict redefinitions

* SINGLE-THREADED-OBJECTS:: See *note STOBJ::.

* STATE:: the von Neumannesque ACL2 state object

* TIME-TRACKER:: display time spent during specified evaluation

* TYPE:: See *note DECLARE::.

* ZERO-TEST-IDIOMS:: how to test for 0


Related topics other than immediate subtopics:
* ACL2-CUSTOMIZATION:: file of initial commands for ACL2 to run at startup

* CERTIFY-BOOK:: how to produce a certificate for a book

* COMP:: compile some ACL2 functions

* COMP-GCL:: compile some ACL2 functions leaving .c and .h files

* DEFCONST:: define a constant

* DEFPKG:: define a new symbol package

* DEFUN:: define a function symbol

* MUTUAL-RECURSION:: define some mutually recursive functions

* SET-BOGUS-MUTUAL-RECURSION-OK:: allow unnecessary ``mutual recursion''

* SET-COMPILE-FNS:: have each function compiled as you go along.

* SET-IGNORE-OK:: allow unused formals and locals without an ignore or ignorable declaration

* SET-IRRELEVANT-FORMALS-OK:: allow irrelevant formals in definitions

* SET-STATE-OK:: allow the use of STATE as a formal parameter

* TIME$:: time an evaluation

* TRACE:: tracing functions in ACL2


File: acl2-doc-emacs.info,  Node: ACL2-BUILT-INS,  Next: ACL2-USER,  Prev: PROGRAMMING,  Up: PROGRAMMING

ACL2-BUILT-INS    built-in ACL2 functions

This documentation topic is a parent topic under which we include
documentation for built-in functions, macros, and special forms that are
typically used in programming.  For others, including those typically
used as top-level commands or those that create events (defun, defthm,
and so on), documentation may be found as a subtopic of some other
parent topic.  We do not document some of the more obscure functions
provided by ACL2 that do not correspond to functions of Common Lisp.

* Menu:

* *:: multiplication macro

* +:: addition macro

* -:: macro for subtraction and negation

* /:: macro for division and reciprocal

* /=:: test inequality of two numbers

* 1+:: increment by 1

* 1-:: decrement by 1

* <:: less-than

* <=:: less-than-or-equal test

* =:: test equality of two numbers

* >:: greater-than test

* >=:: greater-than-or-equal test

* atsign:: (@) get the value of a global variable in state

* ABS:: the absolute value of a real number

* ACL2-COUNT:: a commonly used measure for justifying recursion

* ACL2-NUMBER-LISTP:: recognizer for a true list of numbers

* ACL2-NUMBERP:: recognizer for numbers

* ACONS:: constructor for association lists

* ADD-TO-SET:: add a symbol to a list

* ADD-TO-SET-EQ:: See *note ADD-TO-SET::.

* ADD-TO-SET-EQL:: See *note ADD-TO-SET::.

* ADD-TO-SET-EQUAL:: See *note ADD-TO-SET::.

* ALISTP:: recognizer for association lists

* ALLOCATE-FIXNUM-RANGE:: set aside fixnums in GCL

* ALPHA-CHAR-P:: recognizer for alphabetic characters

* ALPHORDER:: total order on atoms

* AND:: conjunction

* APPEND:: concatenate zero or more lists

* ASH:: arithmetic shift operation

* ASSERT$:: cause a hard error if the given test is false

* ASSIGN:: assign to a global variable in state

* ASSOC:: look up key in association list

* ASSOC-EQ:: See *note ASSOC::.

* ASSOC-EQUAL:: See *note ASSOC::.

* ASSOC-KEYWORD:: look up key in a keyword-value-listp

* ASSOC-STRING-EQUAL:: look up key, a string, in association list

* ATOM:: recognizer for atoms

* ATOM-LISTP:: recognizer for a true list of atoms

* BINARY-*:: multiplication function

* BINARY-+:: addition function

* BINARY-APPEND:: concatenate two lists

* BOOLE$:: perform a bit-wise logical operation on 2 two's complement integers

* BOOLEANP:: recognizer for booleans

* BREAK$:: cause an immediate Lisp break

* BREAKS:: Common Lisp breaks

* BUTLAST:: all but a final segment of a list

* CAAAAR:: car of the caaar

* CAAADR:: car of the caadr

* CAAAR:: car of the caar

* CAADAR:: car of the cadar

* CAADDR:: car of the caddr

* CAADR:: car of the cadr

* CAAR:: car of the car

* CADAAR:: car of the cdaar

* CADADR:: car of the cdadr

* CADAR:: car of the cdar

* CADDAR:: car of the cddar

* CADDDR:: car of the cdddr

* CADDR:: car of the cddr

* CADR:: car of the cdr

* CANONICAL-PATHNAME:: the true absolute filename, with soft links resolved

* CAR:: returns the first element of a non-empty list, else nil

* CASE:: conditional based on if-then-else using eql

* CASE-MATCH:: pattern matching or destructuring

* CDAAAR:: cdr of the caaar

* CDAADR:: cdr of the caadr

* CDAAR:: cdr of the caar

* CDADAR:: cdr of the cadar

* CDADDR:: cdr of the caddr

* CDADR:: cdr of the cadr

* CDAR:: cdr of the car

* CDDAAR:: cdr of the cdaar

* CDDADR:: cdr of the cdadr

* CDDAR:: cdr of the cdar

* CDDDAR:: cdr of the cddar

* CDDDDR:: cdr of the cdddr

* CDDDR:: cdr of the cddr

* CDDR:: cdr of the cdr

* CDR:: returns the second element of a cons pair, else nil

* CEILING:: division returning an integer by truncating toward positive infinity

* CHAR:: the nth element (zero-based) of a string

* CHAR-CODE:: the numeric code for a given character

* CHAR-DOWNCASE:: turn upper-case characters into lower-case characters

* CHAR-EQUAL:: character equality without regard to case

* CHAR-UPCASE:: turn lower-case characters into upper-case characters

* CHAR<:: less-than test for characters

* CHAR<=:: less-than-or-equal test for characters

* CHAR>:: greater-than test for characters

* CHAR>=:: greater-than-or-equal test for characters

* CHARACTER-ALISTP:: recognizer for association lists with characters as keys

* CHARACTER-LISTP:: recognizer for a true list of characters

* CHARACTERP:: recognizer for characters

* CHARACTERS:: characters in ACL2

* CHECK-SUM:: assigning ``often unique'' integers to files and objects

* CLOSE-INPUT-CHANNEL:: See *note IO::.

* CLOSE-OUTPUT-CHANNEL:: See *note IO::.

* CODE-CHAR:: the character corresponding to a given numeric code

* COERCE:: coerce a character list to a string and a string to a list

* COMPLEX:: create an ACL2 number

* COMPLEX-RATIONALP:: recognizes complex rational numbers

* COMPLEX/COMPLEX-RATIONALP:: recognizer for complex numbers

* CONCATENATE:: concatenate lists or strings together

* COND:: conditional based on if-then-else

* CONJUGATE:: complex number conjugate

* CONS:: pair and list constructor

* CONSP:: recognizer for cons pairs

* COUNT:: count the number of occurrences of an item in a string or true-list

* CPU-CORE-COUNT:: the number of cpu cores

* CW:: print to the comment window

* CW!:: print to the comment window

* DELETE-ASSOC:: remove the first pair from an association list for a given key

* DELETE-ASSOC-EQ:: See *note DELETE-ASSOC::.

* DELETE-ASSOC-EQUAL:: See *note DELETE-ASSOC::.

* DENOMINATOR:: divisor of a ratio in lowest terms

* DIGIT-CHAR-P:: the number, if any, corresponding to a given character

* DIGIT-TO-CHAR:: map a digit to a character

* E0-ORD-<:: the old ordering function for ACL2 ordinals

* E0-ORDINALP:: the old recognizer for ACL2 ordinals

* EC-CALL:: execute a call in the ACL2 logic instead of raw Lisp

* EIGHTH:: eighth member of the list

* ENDP:: recognizer for empty lists

* EQ:: equality of symbols

* EQL:: test equality (of two numbers, symbols, or characters)

* EQLABLE-ALISTP:: recognizer for a true list of pairs whose cars are suitable for eql

* EQLABLE-LISTP:: recognizer for a true list of objects each suitable for eql

* EQLABLEP:: the guard for the function eql

* EQUAL:: true equality

* ER:: print an error message and ``cause an error''

* ER-PROGN:: perform a sequence of state-changing ``error triples''

* ERROR1:: print an error message and cause a ``soft error''

* EVENP:: test whether an integer is even

* EXPLODE-NONNEGATIVE-INTEGER:: the list of characters in the radix-r form of a number

* EXPT:: exponential function

* F-GET-GLOBAL:: get the value of a global variable in state

* F-PUT-GLOBAL:: assign to a global variable in state

* FIFTH:: fifth member of the list

* FIRST:: first member of the list

* FIX:: coerce to a number

* FIX-TRUE-LIST:: coerce to a true list

* FLET:: local binding of function symbols

* FLOOR:: division returning an integer by truncating toward negative infinity

* FMS:: :(str alist co-channel state evisc) => state

* FMS!:: :(str alist co-channel state evisc) => state

* FMS!-TO-STRING:: See *note PRINTING-TO-STRINGS::.

* FMS-TO-STRING:: See *note PRINTING-TO-STRINGS::.

* FMT:: formatted printing

* FMT!:: :(str alist co-channel state evisc) => state

* FMT!-TO-STRING:: See *note PRINTING-TO-STRINGS::.

* FMT-TO-COMMENT-WINDOW:: print to the comment window

* FMT-TO-STRING:: See *note PRINTING-TO-STRINGS::.

* FMT1:: :(str alist col co-channel state evisc) => (mv col state)

* FMT1!:: :(str alist col channel state evisc) => (mv col state)

* FMT1!-TO-STRING:: See *note PRINTING-TO-STRINGS::.

* FMT1-TO-STRING:: See *note PRINTING-TO-STRINGS::.

* FOURTH:: fourth member of the list

* GET-OUTPUT-STREAM-STRING$:: See *note IO::.

* GETENV$:: read an environment variable

* GETPROP:: access fast property lists

* GOOD-ATOM-LISTP:: recognizer for a true list of ``good'' atoms

* HARD-ERROR:: print an error message and stop execution

* IDENTITY:: the identity function

* IF:: if-then-else function

* IFF:: logical ``if and only if''

* IFIX:: coerce to an integer

* ILLEGAL:: print an error message and stop execution

* IMAGPART:: imaginary part of a complex number

* IMPLIES:: logical implication

* IMPROPER-CONSP:: recognizer for improper (non-null-terminated) non-empty lists

* INT=:: test equality of two integers

* INTEGER-LENGTH:: number of bits in two's complement integer representation

* INTEGER-LISTP:: recognizer for a true list of integers

* INTEGERP:: recognizer for whole numbers

* INTERN:: create a new symbol in a given package

* INTERN$:: create a new symbol in a given package

* INTERN-IN-PACKAGE-OF-SYMBOL:: create a symbol with a given name

* INTERSECTION$:: elements of one list that are not elements of another

* INTERSECTION-EQ:: See *note INTERSECTION$::.

* INTERSECTION-EQUAL:: See *note INTERSECTION$::.

* INTERSECTP:: test whether two lists intersect

* INTERSECTP-EQ:: See *note INTERSECTP::.

* INTERSECTP-EQUAL:: See *note INTERSECTP::.

* KEYWORD-VALUE-LISTP:: recognizer for true lists whose even-position elements are keywords

* KEYWORDP:: recognizer for keywords

* KWOTE:: quote an arbitrary object

* KWOTE-LST:: quote an arbitrary true list of objects

* LAST:: the last cons (not element) of a list

* LEN:: length of a list

* LENGTH:: length of a string or proper list

* LET:: binding of lexically scoped (local) variables

* LET*:: binding of lexically scoped (local) variables

* LEXORDER:: total order on ACL2 objects

* LIST:: build a list

* LIST*:: build a list

* LISTP:: recognizer for (not necessarily proper) lists

* LOGAND:: bitwise logical `and' of zero or more integers

* LOGANDC1:: bitwise logical `and' of two ints, complementing the first

* LOGANDC2:: bitwise logical `and' of two ints, complementing the second

* LOGBITP:: the ith bit of an integer

* LOGCOUNT:: number of ``on'' bits in a two's complement number

* LOGEQV:: bitwise logical equivalence of zero or more integers

* LOGIOR:: bitwise logical inclusive or of zero or more integers

* LOGNAND:: bitwise logical `nand' of two integers

* LOGNOR:: bitwise logical `nor' of two integers

* LOGNOT:: bitwise not of a two's complement number

* LOGORC1:: bitwise logical inclusive or of two ints, complementing the first

* LOGORC2:: bitwise logical inclusive or of two ints, complementing the second

* LOGTEST:: test if two integers share a `1' bit

* LOGXOR:: bitwise logical exclusive or of zero or more integers

* LOWER-CASE-P:: recognizer for lower case characters

* MAKE-CHARACTER-LIST:: coerce to a list of characters

* MAKE-LIST:: make a list of a given size

* MAKE-ORD:: a constructor for ordinals.

* MAX:: the larger of two numbers

* MBE:: attach code for execution

* MBE1:: attach code for execution

* MBT:: introduce a test not to be evaluated

* MEMBER:: membership predicate

* MEMBER-EQ:: See *note MEMBER::.

* MEMBER-EQUAL:: See *note MEMBER::.

* MIN:: the smaller of two numbers

* MINUSP:: test whether a number is negative

* MOD:: remainder using floor

* MOD-EXPT:: exponential function

* MSG:: construct a ``message'' suitable for the ~@ directive of fmt

* MUST-BE-EQUAL:: attach code for execution

* MV:: returning a multiple value

* MV-LET:: calling multi-valued ACL2 functions

* MV-LIST:: converting multiple-valued result to a single-valued list

* MV-NTH:: the mv-nth element (zero-based) of a list

* MV?:: return one or more values

* MV?-LET:: calling possibly multi-valued ACL2 functions

* NAT-LISTP:: recognizer for a true list of natural  numbers

* NATP:: a recognizer for the natural numbers

* NFIX:: coerce to a natural number

* NINTH:: ninth member of the list

* NO-DUPLICATESP:: check for duplicates in a list

* NO-DUPLICATESP-EQ:: See *note NO-DUPLICATESP::.

* NO-DUPLICATESP-EQUAL:: See *note NO-DUPLICATESP::.

* NON-EXEC:: mark code as non-executable

* NONNEGATIVE-INTEGER-QUOTIENT:: natural number division function

* NOT:: logical negation

* NTH:: the nth element (zero-based) of a list

* NTHCDR:: final segment of a list

* NULL:: recognizer for the empty list

* NUMERATOR:: dividend of a ratio in lowest terms

* O-FINP:: recognizes if an ordinal is finite

* O-FIRST-COEFF:: returns the first coefficient of an ordinal

* O-FIRST-EXPT:: the first exponent of an ordinal

* O-INFP:: recognizes if an ordinal is infinite

* O-P:: a recognizer for the ordinals up to epsilon-0

* O-RST:: returns the rest of an infinite ordinal

* O<:: the well-founded less-than relation on ordinals up to epsilon-0

* O<=:: the less-than-or-equal relation for the ordinals

* O>:: the greater-than relation for the ordinals

* O>=:: the greater-than-or-equal relation for the ordinals

* OBSERVATION:: print an observation

* OBSERVATION-CW:: See *note OBSERVATION::.

* ODDP:: test whether an integer is odd

* OPEN-INPUT-CHANNEL:: See *note IO::.

* OPEN-INPUT-CHANNEL-P:: See *note IO::.

* OPEN-OUTPUT-CHANNEL:: See *note IO::.

* OPEN-OUTPUT-CHANNEL-P:: See *note IO::.

* OR:: disjunction

* ORACLE-APPLY:: call a function argument on the given list of arguments

* ORACLE-APPLY-RAW:: call a function argument on the given list of arguments, no restrictions

* ORACLE-FUNCALL:: call a function argument on the remaining arguments

* PAIRLIS:: See *note PAIRLIS$::

* PAIRLIS$:: zipper together two lists

* PEEK-CHAR$:: See *note IO::.

* PKG-IMPORTS:: list of symbols imported into a given package

* PKG-WITNESS:: return a specific symbol in the indicated package

* PLUSP:: test whether a number is positive

* POSITION:: position of an item in a string or a list

* POSITION-EQ:: See *note POSITION::.

* POSITION-EQUAL:: See *note POSITION::.

* POSP:: a recognizer for the positive integers

* PPROGN:: evaluate a sequence of forms that return state

* PRINC$:: print an atom

* PRINT-OBJECT$:: See *note IO::.

* PROG2$:: execute two forms and return the value of the second one

* PROGN$:: execute a sequence of forms and return the value of the last one

* PROOFS-CO:: the proofs character output channel

* PROPER-CONSP:: recognizer for proper (null-terminated) non-empty lists

* PSEUDO-TERMP:: a predicate for recognizing term-like s-expressions

* PUT-ASSOC:: modify an association list by associating a value with a key

* PUT-ASSOC-EQ:: See *note PUT-ASSOC::.

* PUT-ASSOC-EQL:: See *note PUT-ASSOC::.

* PUT-ASSOC-EQUAL:: See *note PUT-ASSOC::.

* PUTPROP:: update fast property lists

* QUOTE:: create a constant

* R-EQLABLE-ALISTP:: recognizer for a true list of pairs whose cdrs are suitable for eql

* R-SYMBOL-ALISTP:: recognizer for association lists with symbols as values

* RANDOM$:: obtain a random value

* RASSOC:: look up value in association list

* RASSOC-EQ:: See *note RASSOC::.

* RASSOC-EQUAL:: See *note RASSOC::.

* RATIONAL-LISTP:: recognizer for a true list of rational numbers

* RATIONALP:: recognizer for rational numbers (ratios and integers)

* READ-BYTE$:: See *note IO::.

* READ-CHAR$:: See *note IO::.

* READ-OBJECT:: See *note IO::.

* READ-RUN-TIME:: read elapsed runtime

* REAL/RATIONALP:: recognizer for rational numbers (including real number in ACL2(r))

* REALFIX:: coerce to a real number

* REALPART:: real part of a complex number

* REM:: remainder using truncate

* REMOVE:: remove all occurrences

* REMOVE-DUPLICATES:: remove duplicates from a string or a list

* REMOVE-DUPLICATES-EQ:: See *note REMOVE-DUPLICATES::.

* REMOVE-DUPLICATES-EQUAL:: See *note REMOVE-DUPLICATES::.

* REMOVE-EQ:: See *note REMOVE::.

* REMOVE-EQUAL:: See *note REMOVE::.

* REMOVE1:: remove first occurrences, testing using eql

* REMOVE1-EQ:: See *note REMOVE1::.

* REMOVE1-EQUAL:: See *note REMOVE1::.

* REST:: rest (cdr) of the list

* RETURN-LAST:: return the last argument, perhaps with side effects

* REVAPPEND:: concatentate the reverse of one list to another

* REVERSE:: reverse a list or string

* RFIX:: coerce to a rational number

* ROUND:: division returning an integer by rounding off

* SEARCH:: search for a string or list in another string or list

* SECOND:: second member of the list

* SET-DIFFERENCE$:: elements of one list that are not elements of another

* SET-DIFFERENCE-EQ:: See *note SET-DIFFERENCE$::.

* SET-DIFFERENCE-EQUAL:: See *note SET-DIFFERENCE$::.

* SETENV$:: set an environment variable

* SEVENTH:: seventh member of the list

* SIGNED-BYTE-P:: recognizer for signed integers that fit in a specified bit width

* SIGNUM:: indicator for positive, negative, or zero

* SIXTH:: sixth member of the list

* STANDARD-CHAR-LISTP:: recognizer for a true list of standard characters

* STANDARD-CHAR-P:: recognizer for standard characters

* STANDARD-CO:: the character output channel to which ld prints

* STANDARD-OI:: the standard object input ``channel''

* STANDARD-STRING-ALISTP:: recognizer for association lists with standard strings as keys

* STATE-GLOBAL-LET*:: bind state global variables

* STRING:: coerce to a string

* STRING-APPEND:: concatenate two strings

* STRING-DOWNCASE:: in a given string, turn upper-case characters into lower-case

* STRING-EQUAL:: string equality without regard to case

* STRING-LISTP:: recognizer for a true list of strings

* STRING-UPCASE:: in a given string, turn lower-case characters into upper-case

* STRING<:: less-than test for strings

* STRING<=:: less-than-or-equal test for strings

* STRING>:: greater-than test for strings

* STRING>=:: less-than-or-equal test for strings

* STRINGP:: recognizer for strings

* STRIP-CARS:: collect up all first components of pairs in a list

* STRIP-CDRS:: collect up all second components of pairs in a list

* SUBLIS:: substitute an alist into a tree

* SUBSEQ:: subsequence of a string or list

* SUBSETP:: test if every member of one list is a member of the other

* SUBSETP-EQ:: See *note SUBSETP::.

* SUBSETP-EQUAL:: See *note SUBSETP::.

* SUBST:: a single substitution into a tree

* SUBSTITUTE:: substitute into a string or a list, using eql as test

* SYMBOL-<:: less-than test for symbols

* SYMBOL-ALISTP:: recognizer for association lists with symbols as keys

* SYMBOL-LISTP:: recognizer for a true list of symbols

* SYMBOL-NAME:: the name of a symbol (a string)

* SYMBOL-PACKAGE-NAME:: the name of the package of a symbol (a string)

* SYMBOLP:: recognizer for symbols

* SYS-CALL:: make a system call to the host operating system

* SYS-CALL+:: make a system call to the host OS, returning status and output

* SYS-CALL-STATUS:: exit status from the preceding system call

* TAKE:: initial segment of a list

* TENTH:: tenth member of the list

* TERM-ORDER:: the ordering relation on terms used by ACL2

* THE:: run-time type check

* THIRD:: third member of the list

* TIME$:: time an evaluation

* TRUE-LIST-LISTP:: recognizer for true (proper) lists of true lists

* TRUE-LISTP:: recognizer for proper (null-terminated) lists

* TRUNCATE:: division returning an integer by truncating toward 0

* UNARY--:: arithmetic negation function

* UNARY-/:: reciprocal function

* UNION$:: elements of one list that are not elements of another

* UNION-EQ:: See *note UNION$::.

* UNION-EQUAL:: See *note UNION$::.

* UNSIGNED-BYTE-P:: recognizer for natural numbers that fit in a specified bit width

* UNTRANSLATE:: See *note USER-DEFINED-FUNCTIONS-TABLE::.

* UPDATE-NTH:: modify a list by putting the given value at the given position

* UPPER-CASE-P:: recognizer for upper case characters

* WITH-LIVE-STATE:: allow a reference to state in raw Lisp

* WRITE-BYTE$:: See *note IO::.

* XOR:: logical ``exclusive or''

* ZEROP:: test an acl2-number against 0

* ZIP:: testing an ``integer'' against 0

* ZP:: testing a ``natural'' against 0

* ZPF:: testing a nonnegative fixnum against 0

See any documentation for Common Lisp for more details on many of these
functions.


File: acl2-doc-emacs.info,  Node: *,  Next: +,  Prev: ACL2-BUILT-INS,  Up: ACL2-BUILT-INS

*    multiplication macro

* is really a macro that expands to calls of the function binary-*.  So
for example

     (* x y 4 z)

represents the same term as

     (binary-* x (binary-* y (binary-* 4 z))).

See *note BINARY-*::.

* is a Common Lisp function.  See any Common Lisp documentation for
more information.


File: acl2-doc-emacs.info,  Node: +,  Next: -,  Prev: *,  Up: ACL2-BUILT-INS

+    addition macro

+ is really a macro that expands to calls of the function binary-+.  So
for example

     (+ x y 4 z)

represents the same term as

     (binary-+ x (binary-+ y (binary-+ 4 z))).

See *note BINARY-+::.


File: acl2-doc-emacs.info,  Node: -,  Next: /,  Prev: +,  Up: ACL2-BUILT-INS

-    macro for subtraction and negation

See *note BINARY-+:: for addition and see *note UNARY--:: for negation.

Note that - represents subtraction as follows:

     (- x y)

represents the same term as

     (+ x (- y))

which is really

     (binary-+ x (unary-- y)).

Also note that - represents arithmetic negation as follows:

     (- x)

expands to

     (unary-- x).


File: acl2-doc-emacs.info,  Node: /,  Next: /=,  Prev: -,  Up: ACL2-BUILT-INS

/    macro for division and reciprocal

See *note BINARY-*:: for multiplication and see *note UNARY-/:: for
reciprocal.

Note that / represents division as follows:

     (/ x y)

represents the same term as

     (* x (/ y))

which is really

     (binary-* x (unary-/ y)).

Also note that / represents reciprocal as follows:

     (/ x)

expands to

     (unary-/ x).

/ is a Common Lisp macro.  See any Common Lisp documentation for more
information.


File: acl2-doc-emacs.info,  Node: /=,  Next: 1+,  Prev: /,  Up: ACL2-BUILT-INS

/=    test inequality of two numbers

(/= x y) is logically equivalent to (not (equal x y)).

Unlike equal, /= has a guard requiring both of its arguments to be
numbers.  Generally, /= is executed more efficiently than a combination
of not and equal.

For a discussion of the various ways to test against 0, See *note
ZERO-TEST-IDIOMS::.

/= is a Common Lisp function.  See any Common Lisp documentation for
more information.


File: acl2-doc-emacs.info,  Node: 1+,  Next: 1-,  Prev: /=,  Up: ACL2-BUILT-INS

1+    increment by 1

(1+ x) is the same as (+ 1 x).  See *note +::.

1+ is a Common Lisp function.  See any Common Lisp documentation for
more information.


File: acl2-doc-emacs.info,  Node: 1-,  Next: <,  Prev: 1+,  Up: ACL2-BUILT-INS

1-    decrement by 1

(1- x) is the same as (- x 1).  See *note -::.

1- is a Common Lisp function.  See any Common Lisp documentation for
more information.


File: acl2-doc-emacs.info,  Node: <,  Next: <=,  Prev: 1-,  Up: ACL2-BUILT-INS

<    less-than

Completion Axiom (completion-of-<):

     (equal (< x y)
            (if (and (rationalp x)
                     (rationalp y))
                (< x y)
              (let ((x1 (if (acl2-numberp x) x 0))
                    (y1 (if (acl2-numberp y) y 0)))
                (or (< (realpart x1) (realpart y1))
                    (and (equal (realpart x1) (realpart y1))
                         (< (imagpart x1) (imagpart y1)))))))

Guard for (< x y):

     (and (rationalp x) (rationalp y))

Notice that like all arithmetic functions, < treats non-numeric inputs
as 0.

This function has the usual meaning on the rational numbers, but is
extended to the complex rational numbers using the lexicographic order:
first the real parts are compared, and if they are equal, then the
imaginary parts are compared.


File: acl2-doc-emacs.info,  Node: <=,  Next: =,  Prev: <,  Up: ACL2-BUILT-INS

<=    less-than-or-equal test

<= is a macro, and (<= x y) expands to the same thing as (not (< y x)).
See *note <::.

<= is a Common Lisp function.  See any Common Lisp documentation for
more information.


File: acl2-doc-emacs.info,  Node: =,  Next: >,  Prev: <=,  Up: ACL2-BUILT-INS

=    test equality of two numbers

(= x y) is logically equivalent to (equal x y).

Unlike equal, = has a guard requiring both of its arguments to be
numbers.  Generally, = is executed more efficiently than equal.

For a discussion of the various ways to test against 0, See *note
ZERO-TEST-IDIOMS::.

= is a Common Lisp function.  See any Common Lisp documentation for
more information.


File: acl2-doc-emacs.info,  Node: >,  Next: >=,  Prev: =,  Up: ACL2-BUILT-INS

>    greater-than test

> is a macro, and (> x y) expands to the same thing as (< y x).  See
*note <::.

> is a Common Lisp function.  See any Common Lisp documentation for
more information.


File: acl2-doc-emacs.info,  Node: >=,  Next: atsign,  Prev: >,  Up: ACL2-BUILT-INS

>=    greater-than-or-equal test

>= is a macro, and (>= x y) expands to the same thing as (not (< x y)).
See *note <::.

>= is a Common Lisp function.  See any Common Lisp documentation for
more information.


File: acl2-doc-emacs.info,  Node: atsign,  Next: ABS,  Prev: >=,  Up: ACL2-BUILT-INS

@    get the value of a global variable in state

     Examples:
     (+ (@ y) 1)
     (assign a (aset1 'ascii-map-array (@ a) 66 'Upper-case-B))

     General Form:
     (@ symbol)

where symbol is any symbol to which you have assigned a global value.
This macro expands into (f-get-global 'symbol state), which retrieves
the stored value of the symbol.

The macro f-get-global is closely related to @: (@ var) macroexpands to
(f-get-global 'var state).

The macro assign makes it convenient to set the value of a symbol.  The
:ubt operation has no effect on the global-table of state.  Thus, you
may use these globals to hang onto useful data structures even though
you may undo back past where you computed and saved them.


File: acl2-doc-emacs.info,  Node: ABS,  Next: ACL2-COUNT,  Prev: atsign,  Up: ACL2-BUILT-INS

ABS    the absolute value of a real number

(Abs x) is -x if x is negative and is x otherwise.

The guard for abs requires its argument to be a rational (real, in
ACL2(r)) number.

Abs is a Common Lisp function.  See any Common Lisp documentation for
more information.

From "Common Lisp the Language" page 205, we must not allow complex x
as an argument to abs in ACL2, because if we did we would have to
return a number that might be a floating point number and hence not an
ACL2 object.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: ACL2-COUNT,  Next: ACL2-NUMBER-LISTP,  Prev: ABS,  Up: ACL2-BUILT-INS

ACL2-COUNT    a commonly used measure for justifying recursion

(Acl2-count x) returns a nonnegative integer that indicates the "size"
of its argument x.

All characters and symbols have acl2-count 0.  The acl2-count of a
string is the number of characters in it, i.e., its length.  The
acl2-count of a cons is one greater than the sum of the acl2-counts of
the car and cdr.  The acl2-count of an integer is its absolute value.
The acl2-count of a rational is the sum of the acl2-counts of the
numerator and denominator.  The acl2-count of a complex rational is one
greater than the sum of the acl2-counts of the real and imaginary parts.


File: acl2-doc-emacs.info,  Node: ACL2-NUMBER-LISTP,  Next: ACL2-NUMBERP,  Prev: ACL2-COUNT,  Up: ACL2-BUILT-INS

ACL2-NUMBER-LISTP    recognizer for a true list of numbers

The predicate acl2-number-listp tests whether its argument is a true
list of numbers.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: ACL2-NUMBERP,  Next: ACONS,  Prev: ACL2-NUMBER-LISTP,  Up: ACL2-BUILT-INS

ACL2-NUMBERP    recognizer for numbers

(acl2-numberp x) is true if and only if x is a number, i.e., a rational
or complex rational number.


File: acl2-doc-emacs.info,  Node: ACONS,  Next: ADD-TO-SET,  Prev: ACL2-NUMBERP,  Up: ACL2-BUILT-INS

ACONS    constructor for association lists

(Acons key datum alist) equals the result of consing the pair (cons key
datum) to the front of the association list alist.

(Acons key datum alist) has a guard of (alistp alist).  Acons is a
Common Lisp function.  See any Common Lisp documentation for more
information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: ADD-TO-SET,  Next: ADD-TO-SET-EQ,  Prev: ACONS,  Up: ACL2-BUILT-INS

ADD-TO-SET    add a symbol to a list

     General Forms:
     (add-to-set x lst)
     (add-to-set x lst :test 'eql)   ; same as above (eql as equality test)
     (add-to-set x lst :test 'eq)    ; same, but eq is equality test
     (add-to-set x lst :test 'equal) ; same, but equal is equality test

For a symbol x and an object lst, (add-to-set-eq x lst) is the result
of consing x on to the front of lst, unless x is already a member of
lst, in which case the result is lst. The optional keyword, :TEST, has
no effect logically, but provides the test (default eql) used for
comparing x with successive elements of lst.

The guard for a call of add-to-set depends on the test.  In all cases,
the second argument must satisfy true-listp.  If the test is eql, then
either the first argument must be suitable for eql (see *note
EQLABLEP::) or the second argument must satisfy eqlable-listp.  If the
test is eq, then either the first argument must be a symbol or the
second argument must satisfy symbol-listp.

See *note EQUALITY-VARIANTS:: for a discussion of the relation between
add-to-set and its variants:

     (add-to-set-eq x lst) is equivalent to (add-to-set x lst :test
     'eq);

     (add-to-set-equal x lst) is equivalent to (add-to-set x lst :test
     'equal).


In particular, reasoning about any of these primitives reduces to
reasoning about the function add-to-set-equal.


File: acl2-doc-emacs.info,  Node: ADD-TO-SET-EQ,  Next: ADD-TO-SET-EQL,  Prev: ADD-TO-SET,  Up: ACL2-BUILT-INS

ADD-TO-SET-EQ    See *note ADD-TO-SET::.


File: acl2-doc-emacs.info,  Node: ADD-TO-SET-EQL,  Next: ADD-TO-SET-EQUAL,  Prev: ADD-TO-SET-EQ,  Up: ACL2-BUILT-INS

ADD-TO-SET-EQL    See *note ADD-TO-SET::.


File: acl2-doc-emacs.info,  Node: ADD-TO-SET-EQUAL,  Next: ALISTP,  Prev: ADD-TO-SET-EQL,  Up: ACL2-BUILT-INS

ADD-TO-SET-EQUAL    See *note ADD-TO-SET::.


File: acl2-doc-emacs.info,  Node: ALISTP,  Next: ALLOCATE-FIXNUM-RANGE,  Prev: ADD-TO-SET-EQUAL,  Up: ACL2-BUILT-INS

ALISTP    recognizer for association lists

(alistp x) is true if and only if x is a list of cons pairs.

(alistp x) has a guard of t.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: ALLOCATE-FIXNUM-RANGE,  Next: ALPHA-CHAR-P,  Prev: ALISTP,  Up: ACL2-BUILT-INS

ALLOCATE-FIXNUM-RANGE    set aside fixnums in GCL

(Allocate-fixnum-range fixnum-lo fixnum-hi) causes Gnu Common Lisp
(GCL) to create a persistent table for the integers between fixnum-lo
and fixnum-hi (both bounds inclusive). This table is referenced first
when any integer is boxed and the existing box in the table is used if
the integer is in bounds.  This can speed up GCL considerably by
avoiding wasteful fixnum boxing.  Here, fixnum-lo and fixnum-hi should
be fixnums.  On 32-bit machines it would be good for them to be of type
(signed-byte 30), with fixnum-lo <= fixnum-hi.

When this function is executed in a Lisp implementation other than GCL,
it has no side effect.  This function always returns nil.


File: acl2-doc-emacs.info,  Node: ALPHA-CHAR-P,  Next: ALPHORDER,  Prev: ALLOCATE-FIXNUM-RANGE,  Up: ACL2-BUILT-INS

ALPHA-CHAR-P    recognizer for alphabetic characters

(Alpha-char-p x) is true if and only if x is a alphabetic character,
i.e., one of the characters #\a, #\b, ..., #\z, #\A, #\B, ..., #\Z.

The guard for alpha-char-p requires its argument to be a character.

Alpha-char-p is a Common Lisp function.  See any Common Lisp
documentation for more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: ALPHORDER,  Next: AND,  Prev: ALPHA-CHAR-P,  Up: ACL2-BUILT-INS

ALPHORDER    total order on atoms

Alphorder is a non-strict total order, a "less than or equal," on
atoms.  By "non-strict total order" we mean a function that always
returns t or nil and satisfies the following properties.

     o Antisymmetry:  XrY & YrX -> X=Y

     o Transitivity:  XrY & YrZ -> XrZ

     o Trichotomy:  XrY v YrX

Also see *note LEXORDER::, which extends alphorder to all objects.

(Alphorder x y) has a guard of (and (atom x) (atom y)).

Within a single type: rationals are compared arithmetically, complex
rationals are compared lexicographically, characters are compared via
their char-codes, and strings and symbols are compared with alphabetic
ordering.  Across types, rationals come before complexes, complexes
come before characters, characters before strings, and strings before
symbols.  We also allow for "bad atoms," i.e., atoms that are not legal
Lisp objects but make sense in the ACL2 logic; these come at the end,
after symbols.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: AND,  Next: APPEND,  Prev: ALPHORDER,  Up: ACL2-BUILT-INS

AND    conjunction

And is the macro for conjunctions.  And takes any number of arguments.
And returns nil if one of the arguments is nil, but otherwise returns
the last argument.  If there are no arguments, and returns t.

And is a Common Lisp macro.  See any Common Lisp documentation for more
information.


File: acl2-doc-emacs.info,  Node: APPEND,  Next: ASH,  Prev: AND,  Up: ACL2-BUILT-INS

APPEND    concatenate zero or more lists

Append, which takes zero or more arguments, expects all the arguments
except perhaps the last to be true (null-terminated) lists.  It returns
the result of concatenating all the elements of all the given lists
into a single list.  Actually, in ACL2 append is a macro that expands
into calls of the binary function binary-append if there are at least
two arguments; if there is just one argument then the expansion is that
argument; and finally, (append) expands to nil.

Append is a Common Lisp function.  See any Common Lisp documentation for
more information.


File: acl2-doc-emacs.info,  Node: ASH,  Next: ASSERT$,  Prev: APPEND,  Up: ACL2-BUILT-INS

ASH    arithmetic shift operation

(ash i c) is the result of taking the two's complement representation
of the integer i and shifting it by c bits:  shifting left and padding
with c 0 bits if c is positive, shifting right and dropping (abs c)
bits if c is negative, and simply returning i if c is 0.

The guard for ash requires that its arguments are integers.

Ash is a Common Lisp function.  See any Common Lisp documentation for
more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: ASSERT$,  Next: ASSIGN,  Prev: ASH,  Up: ACL2-BUILT-INS

ASSERT$    cause a hard error if the given test is false

     General Form:
     (assert$ test form)

where test returns a single value and form is arbitrary.  Semantically,
this call of assert$ is equivalent to form.  However, it causes a hard
error if the value of test is nil.  That hard error invokes the
function illegal, which has a guard that is equal to nil; so if you use
assert$ in code for which you verify guards, then a proof obligation
will be that the occurrence of test is never nil.


File: acl2-doc-emacs.info,  Node: ASSIGN,  Next: ASSOC,  Prev: ASSERT$,  Up: ACL2-BUILT-INS

ASSIGN    assign to a global variable in state

     Examples:
     (assign x (expt 2 10))
     (assign a (aset1 'ascii-map-array (@ a) 66 'Upper-case-B))

     General Form:
     (assign symbol term)

where symbol is any symbol (with certain enforced exclusions to avoid
overwriting ACL2 system "globals") and term is any ACL2 term that could
be evaluated at the top-level.  Assign evaluates the term, stores the
result as the value of the given symbol in the global-table of state,
and returns the result.  (Note:  the actual implementation of the
storage of this value is much more efficient than this discussion of
the logic might suggest.)  Assign is a macro that effectively expands
to the more complicated but understandable:

     (pprogn (f-put-global 'symbol term state)
             (mv nil (f-get-global 'symbol state) state)).

The macro f-put-global is closely related to assign: (assign var val)
macroexpands to (f-put-global 'var val state).

The macro @ gives convenient access to the value of such globals.  The
:ubt operation has no effect on the global-table of state.  Thus, you
may use these globals to hang onto useful data structures even though
you may undo back past where you computed and saved them.


File: acl2-doc-emacs.info,  Node: ASSOC,  Next: ASSOC-EQ,  Prev: ASSIGN,  Up: ACL2-BUILT-INS

ASSOC    look up key in association list

     General Forms:
     (assoc x alist)
     (assoc x alist :test 'eql)   ; same as above (eql as equality test)
     (assoc x alist :test 'eq)    ; same, but eq is equality test
     (assoc x alist :test 'equal) ; same, but equal is equality test

(Assoc x alist) is the first member of alist whose car is x, or nil if
no such member exists.  The optional keyword, :TEST, has no effect
logically, but provides the test (default eql) used for comparing x
with the cars of successive elements of alist.

The guard for a call of assoc depends on the test.  In all cases, the
second argument must satisfy alistp.  If the test is eql, then either
the first argument must be suitable for eql (see *note EQLABLEP::) or
the second argument must satisfy eqlable-alistp.  If the test is eq,
then either the first argument must be a symbol or the second argument
must satisfy symbol-alistp.

See *note EQUALITY-VARIANTS:: for a discussion of the relation between
assoc and its variants:

     (assoc-eq x alist) is equivalent to (assoc x alist :test 'eq);

     (assoc-equal x alist) is equivalent to (assoc x alist :test
     'equal).


In particular, reasoning about any of these primitives reduces to
reasoning about the function assoc-equal.

Assoc is defined by Common Lisp.  See any Common Lisp documentation for
more information.


File: acl2-doc-emacs.info,  Node: ASSOC-EQ,  Next: ASSOC-EQUAL,  Prev: ASSOC,  Up: ACL2-BUILT-INS

ASSOC-EQ    See *note ASSOC::.


File: acl2-doc-emacs.info,  Node: ASSOC-EQUAL,  Next: ASSOC-KEYWORD,  Prev: ASSOC-EQ,  Up: ACL2-BUILT-INS

ASSOC-EQUAL    See *note ASSOC::.


File: acl2-doc-emacs.info,  Node: ASSOC-KEYWORD,  Next: ASSOC-STRING-EQUAL,  Prev: ASSOC-EQUAL,  Up: ACL2-BUILT-INS

ASSOC-KEYWORD    look up key in a keyword-value-listp

If l is a list of even length of the form (k1 a1 k2 a2 ... kn an),
where each ki is a keyword, then (assoc-keyword key l) is the first
tail of l starting with key if key is some ki, and is nil otherwise.

The guard for (assoc-keyword key l) is (keyword-value-listp l).

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: ASSOC-STRING-EQUAL,  Next: ATOM,  Prev: ASSOC-KEYWORD,  Up: ACL2-BUILT-INS

ASSOC-STRING-EQUAL    look up key, a string, in association list

(Assoc-string-equal x alist) is similar to assoc-equal.  However, for
string x and alist alist, the comparison of x with successive keys in
alist is done using string-equal rather than equal.

The guard for assoc-string-equal requires that x is a string and alist
is an alist.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: ATOM,  Next: ATOM-LISTP,  Prev: ASSOC-STRING-EQUAL,  Up: ACL2-BUILT-INS

ATOM    recognizer for atoms

(atom x) is true if and only if x is an atom, i.e., not a cons pair.

Atom has a guard of t, and is a Common Lisp function.  See any Common
Lisp documentation for more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: ATOM-LISTP,  Next: BINARY-*,  Prev: ATOM,  Up: ACL2-BUILT-INS

ATOM-LISTP    recognizer for a true list of atoms

The predicate atom-listp tests whether its argument is a true-listp of
atoms, i.e., of non-conses.

Also see *note GOOD-ATOM-LISTP::.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: BINARY-*,  Next: BINARY-+,  Prev: ATOM-LISTP,  Up: ACL2-BUILT-INS

BINARY-*    multiplication function

Completion Axiom (completion-of-*):

     (equal (binary-* x y)
            (if (acl2-numberp x)
                (if (acl2-numberp y)
                    (binary-* x y)
                  0)
              0))

Guard for (binary-* x y):

     (and (acl2-numberp x) (acl2-numberp y))

Notice that like all arithmetic functions, binary-* treats non-numeric
inputs as 0.

Calls of the macro * expand to calls of binary-*; see *note *::.


File: acl2-doc-emacs.info,  Node: BINARY-+,  Next: BINARY-APPEND,  Prev: BINARY-*,  Up: ACL2-BUILT-INS

BINARY-+    addition function

Completion Axiom (completion-of-+):

     (equal (binary-+ x y)
            (if (acl2-numberp x)
                (if (acl2-numberp y)
                    (binary-+ x y)
                  x)
              (if (acl2-numberp y)
                  y
                0)))

Guard for (binary-+ x y):

     (and (acl2-numberp x) (acl2-numberp y))

Notice that like all arithmetic functions, binary-+ treats non-numeric
inputs as 0.

Calls of the macro + expand to calls of binary-+; see *note +::.


File: acl2-doc-emacs.info,  Node: BINARY-APPEND,  Next: BOOLE$,  Prev: BINARY-+,  Up: ACL2-BUILT-INS

BINARY-APPEND    concatenate two lists

This binary function implements append, which is a macro in ACL2.  See
*note APPEND::

The guard for binary-append requires the first argument to be a
true-listp.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: BOOLE$,  Next: BOOLEANP,  Prev: BINARY-APPEND,  Up: ACL2-BUILT-INS

BOOLE$    perform a bit-wise logical operation on 2 two's complement integers

When integers x and y are viewed in their two's complement
representation, (boole$ op x y) returns the result of applying the
bit-wise logical operation specified by op.  The following table is
adapted from documentation for analogous Common Lisp function boole in
the Common Lisp HyperSpec
(`http://www.lisp.org/HyperSpec/Body/fun_boole.html#boole').  Note that
the values of op for boole$ are ACL2 constants, rather than
corresponding values of op for the Common Lisp function boole.

     op               result
     -----------      ---------
     *boole-1*        x
     *boole-2*        y
     *boole-andc1*    and complement of x with y
     *boole-andc2*    and x with complement of y
     *boole-and*      and
     *boole-c1*       complement of x
     *boole-c2*       complement of y
     *boole-clr*      the constant 0 (all zero bits)
     *boole-eqv*      equivalence (exclusive nor)
     *boole-ior*      inclusive or
     *boole-nand*     not-and
     *boole-nor*      not-or
     *boole-orc1*     or complement of x with y
     *boole-orc2*     or x with complement of y
     *boole-set*      the constant -1 (all one bits)
     *boole-xor*      exclusive or

The guard of boole$ specifies that op is the value of one of the
constants above and that x and y are integers.

See any Common Lisp documentation for analogous information about
Common Lisp function boole.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: BOOLEANP,  Next: BREAK$,  Prev: BOOLE$,  Up: ACL2-BUILT-INS

BOOLEANP    recognizer for booleans

(Booleanp x) is t if x is t or nil, and is nil otherwise.

See *note GENERALIZED-BOOLEANS:: for a discussion of a potential
soundness problem for ACL2 related to the question:  Which Common Lisp
functions are known to return Boolean values?

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: BREAK$,  Next: BREAKS,  Prev: BOOLEANP,  Up: ACL2-BUILT-INS

BREAK$    cause an immediate Lisp break

ACL2 users are generally advised to avoid breaking into raw Lisp.
Advanced users may, on occasion, see the need to do so.  Evaluating
(break$) will have that effect.  (Exception: break$ is disabled after
evaluation of (set-debugger-enable :never); see *note
SET-DEBUGGER-ENABLE::.)  Break$ returns nil.


File: acl2-doc-emacs.info,  Node: BREAKS,  Next: BUTLAST,  Prev: BREAK$,  Up: ACL2-BUILT-INS

BREAKS    Common Lisp breaks

     Example:
     Broken at PROVE.  Type :H for Help.
     >>:Q

     ACL2 !>

You may interrupt the system by typing various control character
sequences.  The precise sequences are determined by the host Lisp and
operating system environment.  For example, in GCL and Allegro Common
Lisp, a console interrupt is caused by typing "ctrl-c".  If, however,
the GCL or Allegro is running in an Emacs shell buffer, one must type
"ctrl-c ctrl-c".

If a break occurs, for example because of a bug in ACL2 or a user
interrupt, the break will run a Common Lisp read-eval-print loop, not
an ACL2 read-eval-print loop.  This may not be obvious if the prompts
in the two loops are similar.  Because you are typing to a Common Lisp
evaluator, you must be careful.  It is possible to damage your ACL2
state in irreparable ways by executing non-ACL2 Common Lisp.  It is
even possible to disrupt and render inaccurate the interrupted
evaluation of a simple ACL2 expression.

For ACL2 built on most host Common Lisps, you will see the string [RAW
LISP] in the prompt at a break, to emphasize that one is inside a break
and hence should quit from the break.  For some host Common Lisps, the
top-level prompt also contains the string [RAW LISP].  See *note
PROMPT:: for how to control printing of that string.

The most reliable way to return to the ACL2 top level is by executing
the following command: (abort!).  Appropriate cleanup will then be
done, which should leave you in an appropriate state.

However, you may be able to quit from the break in the normal Lisp
manner (as with :q in GCL or CCL, :reset in Allegro CL, and q in CMU
CL).  If this attempt to quit is successful, it will return you to the
innermost ACL2 read-eval-print loop, with appropriate cleanup performed
first.  Note that if you are within a brr environment when the break
occurs, quitting from the break will only return you to that
environment, not to the top of ACL2's read-eval-print loop.


File: acl2-doc-emacs.info,  Node: BUTLAST,  Next: CAAAAR,  Prev: BREAKS,  Up: ACL2-BUILT-INS

BUTLAST    all but a final segment of a list

(Butlast l n) is the list obtained by removing the last n elements from
the true list l.  The following is a theorem (though it takes some
effort, including lemmas, to get ACL2 to prove it).

     (implies (and (integerp n)
                   (<= 0 n)
                   (true-listp l))
              (equal (length (butlast l n))
                     (if (< n (length l))
                         (- (length l) n)
                       0)))

For related functions, see *note TAKE:: and see *note NTHCDR::.

The guard for (butlast l n) requires that n is a nonnegative integer
and lst is a true list.

Butlast is a Common Lisp function.  See any Common Lisp documentation
for more information.  Note:  In Common Lisp the second argument of
butlast is optional, but in ACL2 it is required.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: CAAAAR,  Next: CAAADR,  Prev: BUTLAST,  Up: ACL2-BUILT-INS

CAAAAR    car of the caaar

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: CAAADR,  Next: CAAAR,  Prev: CAAAAR,  Up: ACL2-BUILT-INS

CAAADR    car of the caadr

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: CAAAR,  Next: CAADAR,  Prev: CAAADR,  Up: ACL2-BUILT-INS

CAAAR    car of the caar

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: CAADAR,  Next: CAADDR,  Prev: CAAAR,  Up: ACL2-BUILT-INS

CAADAR    car of the cadar

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: CAADDR,  Next: CAADR,  Prev: CAADAR,  Up: ACL2-BUILT-INS

CAADDR    car of the caddr

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: CAADR,  Next: CAAR,  Prev: CAADDR,  Up: ACL2-BUILT-INS

CAADR    car of the cadr

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: CAAR,  Next: CADAAR,  Prev: CAADR,  Up: ACL2-BUILT-INS

CAAR    car of the car

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: CADAAR,  Next: CADADR,  Prev: CAAR,  Up: ACL2-BUILT-INS

CADAAR    car of the cdaar

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: CADADR,  Next: CADAR,  Prev: CADAAR,  Up: ACL2-BUILT-INS

CADADR    car of the cdadr

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: CADAR,  Next: CADDAR,  Prev: CADADR,  Up: ACL2-BUILT-INS

CADAR    car of the cdar

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: CADDAR,  Next: CADDDR,  Prev: CADAR,  Up: ACL2-BUILT-INS

CADDAR    car of the cddar

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: CADDDR,  Next: CADDR,  Prev: CADDAR,  Up: ACL2-BUILT-INS

CADDDR    car of the cdddr

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: CADDR,  Next: CADR,  Prev: CADDDR,  Up: ACL2-BUILT-INS

CADDR    car of the cddr

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: CADR,  Next: CANONICAL-PATHNAME,  Prev: CADDR,  Up: ACL2-BUILT-INS

CADR    car of the cdr

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: CANONICAL-PATHNAME,  Next: CAR,  Prev: CADR,  Up: ACL2-BUILT-INS

CANONICAL-PATHNAME    the true absolute filename, with soft links resolved

For the name fname of a file, the form (Canonical-pathname fname nil
state) evaluates to a Unix-style absolute filename representing the
same file as fname, but generally without any use of soft links in the
name.  (Below, we explain the qualifier "generally".)  If however the
file indicated by fname does not exist, (canonical-pathname fname nil
state) is nil.  Thus, canonical-pathname can be used as one would use
the raw Lisp function probe-file.

The specification of (Canonical-pathname fname dir-p state) when dir-p
is not nil is simlar, except that if the specified file exists but is
not a directory, then the result is nil.

The function canonical-pathname has a guard of t, though the second
argument must be the ACL2 state.  This function is introduced with the
following properties.

     (defthm canonical-pathname-is-idempotent
       (equal (canonical-pathname (canonical-pathname x dir-p state) dir-p state)
              (canonical-pathname x dir-p state)))
     (defthm canonical-pathname-type
       (or (equal (canonical-pathname x dir-p state) nil)
           (stringp (canonical-pathname x dir-p state)))
       :rule-classes :type-prescription)

We use the qualifier "generally", above, because there is no guarantee
that the filename will be canonical without soft links, though we
expect this to be true in practice.  ACL2 attempts to compute the
desired result and then checks that the input and result have the same
Common Lisp "truename".  This check is expected to succeed, but if it
fails then the input string is returned unchanged, and to be
conservative, the value returned is nil in this case if dir-p is true.


File: acl2-doc-emacs.info,  Node: CAR,  Next: CASE,  Prev: CANONICAL-PATHNAME,  Up: ACL2-BUILT-INS

CAR    returns the first element of a non-empty list, else nil

Completion Axiom (completion-of-car):

     (equal (car x)
            (cond
             ((consp x)
              (car x))
             (t nil)))

Guard:

     (or (consp x) (equal x nil))

Notice that in the ACL2 logic, car returns nil for every atom.


File: acl2-doc-emacs.info,  Node: CASE,  Next: CASE-MATCH,  Prev: CAR,  Up: ACL2-BUILT-INS

CASE    conditional based on if-then-else using eql

     Example Form:
     (case typ
       ((:character foo)
        (open file-name :direction :output))
       (bar (open-for-bar file-name))
       (otherwise
        (my-error "Illegal.")))

is the same as

     (cond ((member typ '(:character foo))
            (open file-name :direction :output))
           ((eql typ 'bar)
            (open-for-bar file-name))
           (t (my-error "Illegal.")))

which in turn is the same as

     (if (member typ '(:character foo))
         (open file-name :direction :output)
         (if (eql typ 'bar)
             (open-for-bar file-name)
             (my-error "Illegal.")))

Notice the quotations that appear in the example above: '(:character
foo) and 'bar.

     General Forms:
     (case expr
       (x1 val-1)
       ...
       (xk val-k)
       (otherwise val-k+1))

     (case expr
       (x1 val-1)
       ...
       (xk val-k)
       (t val-k+1))

     (case expr
       (x1 val-1)
       ...
       (xk val-k))

where each xi is either eqlablep or a true list of eqlablep objects.
The final otherwise or t case is optional.

Case is defined in Common Lisp.  See any Common Lisp documentation for
more information.


File: acl2-doc-emacs.info,  Node: CASE-MATCH,  Next: CDAAAR,  Prev: CASE,  Up: ACL2-BUILT-INS

CASE-MATCH    pattern matching or destructuring

     General Form:
     (case-match x
       (pat1 dcl1 body1)
       ...
       (patk dclk bodyk))

where x is a variable symbol, the pati are structural patterns as
described below, the dcli are optional declare forms and the bodyi are
terms.  Return the value(s) of the bodyi corresponding to the first
pati matching x, or nil if none matches.

Pattern Language:
With the few special exceptions described below, matching requires that
the cons structure of x be isomorphic to that of the pattern, down to
the atoms in the pattern.  Non-symbol atoms in the pattern match only
themselves.  Symbols in the pattern denote variables which match
anything and which are bound by a successful match to the corresponding
substructure of x.  Variables that occur more than once must match the
same (EQUAL) structure in every occurrence.

     Exceptions:
     &               Matches anything and is not bound.  Repeated
                       occurrences of & in a pattern may match different
                       structures.
     nil, t, *sym*   These symbols cannot be bound and match only their
                       global values.
     !sym            where sym is a symbol that is already bound in the
                       context of the case-match, matches only the
                       current binding of sym.
     'obj            Matches only itself.

Some examples are shown below.

Below we show some sample patterns and examples of things they match
and do not match.

     pattern       matches         non-matches
     (x y y)       (ABC 3 3)       (ABC 3 4)    ; 3 is not 4
     (fn x . rst)  (P (A I) B C)   (ABC)        ; NIL is not (x . rst)
                   (J (A I))                    ; rst matches nil
     ('fn (g x) 3) (FN (H 4) 3)    (GN (G X) 3) ; 'fn matches only itself
     (& t & !x)    ((A) T (B) (C))              ; provided x is '(C)

Consider the two binary trees that contain three leaves.  They might be
described as (x . (y . z)) and ((x . y) . z), where x, y, and z are
atomic.  Suppose we wished to recognize those trees.  The following
case-match would do:

     (case-match tree
       ((x . (y . z))
        (and (atom x) (atom y) (atom z)))
       (((x . y) . z)
        (and (atom x) (atom y) (atom z))))

Suppose we wished to recognize such trees where all three tips are
identical.  Suppose further we wish to return the tip if the tree is
one of those recognized ones and to return the number 7 otherwise.

     (case-match tree
       ((x . (x . x))
        (if (atom x) x 7))
       (((x . x) . x)
        (if (atom x) x 7))
       (& 7))

Note that case-match returns nil if no pati matches.  Thus if we must
return 7 in that case, we have to add as the final pattern the &, which
always matches anything.


File: acl2-doc-emacs.info,  Node: CDAAAR,  Next: CDAADR,  Prev: CASE-MATCH,  Up: ACL2-BUILT-INS

CDAAAR    cdr of the caaar

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: CDAADR,  Next: CDAAR,  Prev: CDAAAR,  Up: ACL2-BUILT-INS

CDAADR    cdr of the caadr

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: CDAAR,  Next: CDADAR,  Prev: CDAADR,  Up: ACL2-BUILT-INS

CDAAR    cdr of the caar

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: CDADAR,  Next: CDADDR,  Prev: CDAAR,  Up: ACL2-BUILT-INS

CDADAR    cdr of the cadar

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: CDADDR,  Next: CDADR,  Prev: CDADAR,  Up: ACL2-BUILT-INS

CDADDR    cdr of the caddr

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: CDADR,  Next: CDAR,  Prev: CDADDR,  Up: ACL2-BUILT-INS

CDADR    cdr of the cadr

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: CDAR,  Next: CDDAAR,  Prev: CDADR,  Up: ACL2-BUILT-INS

CDAR    cdr of the car

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: CDDAAR,  Next: CDDADR,  Prev: CDAR,  Up: ACL2-BUILT-INS

CDDAAR    cdr of the cdaar

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: CDDADR,  Next: CDDAR,  Prev: CDDAAR,  Up: ACL2-BUILT-INS

CDDADR    cdr of the cdadr

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: CDDAR,  Next: CDDDAR,  Prev: CDDADR,  Up: ACL2-BUILT-INS

CDDAR    cdr of the cdar

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: CDDDAR,  Next: CDDDDR,  Prev: CDDAR,  Up: ACL2-BUILT-INS

CDDDAR    cdr of the cddar

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: CDDDDR,  Next: CDDDR,  Prev: CDDDAR,  Up: ACL2-BUILT-INS

CDDDDR    cdr of the cdddr

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: CDDDR,  Next: CDDR,  Prev: CDDDDR,  Up: ACL2-BUILT-INS

CDDDR    cdr of the cddr

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: CDDR,  Next: CDR,  Prev: CDDDR,  Up: ACL2-BUILT-INS

CDDR    cdr of the cdr

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: CDR,  Next: CEILING,  Prev: CDDR,  Up: ACL2-BUILT-INS

CDR    returns the second element of a cons pair, else nil

Completion Axiom (completion-of-cdr):

     (equal (cdr x)
            (cond
             ((consp x)
              (cdr x))
             (t nil)))

Guard:

     (or (consp x) (equal x nil))

Notice that in the ACL2 logic, cdr returns nil for every atom.


File: acl2-doc-emacs.info,  Node: CEILING,  Next: CHAR,  Prev: CDR,  Up: ACL2-BUILT-INS

CEILING    division returning an integer by truncating toward positive infinity

     Example Forms:
     ACL2 !>(ceiling 14 3)
     5
     ACL2 !>(ceiling -14 3)
     -4
     ACL2 !>(ceiling 14 -3)
     -4
     ACL2 !>(ceiling -14 -3)
     5
     ACL2 !>(ceiling -15 -3)
     5

(Ceiling i j) is the result of taking the quotient of i and j and
returning the smallest integer that is at least as great as that
quotient.  For example, the quotient of -14 by 3 is -4 2/3, and the
smallest integer at least that great is -4.

The guard for (ceiling i j) requires that i and j are rational (real,
in ACL2(r)) numbers and j is non-zero.

Ceiling is a Common Lisp function.  See any Common Lisp documentation
for more information.  However, note that unlike Common Lisp, the ACL2
ceiling function returns only a single value,

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: CHAR,  Next: CHAR-CODE,  Prev: CEILING,  Up: ACL2-BUILT-INS

CHAR    the nth element (zero-based) of a string

(Char s n) is the nth element of s, zero-based.  If n is greater than
or equal to the length of s, then char returns nil.

(Char s n) has a guard that n is a non-negative integer and s is a
stringp.

Char is a Common Lisp function.  See any Common Lisp documentation for
more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: CHAR-CODE,  Next: CHAR-DOWNCASE,  Prev: CHAR,  Up: ACL2-BUILT-INS

CHAR-CODE    the numeric code for a given character

Completion Axiom (completion-of-char-code):

     (equal (char-code x)
            (if (characterp x)
                (char-code x)
              0))

Guard for (char-code x):

     (characterp x)

This function maps all non-characters to 0.


File: acl2-doc-emacs.info,  Node: CHAR-DOWNCASE,  Next: CHAR-EQUAL,  Prev: CHAR-CODE,  Up: ACL2-BUILT-INS

CHAR-DOWNCASE    turn upper-case characters into lower-case characters

(Char-downcase x) is equal to #\a when x is #\A, #\b when x is #\B,
..., and #\z when x is #\Z, and is x for any other character.

The guard for char-downcase requires its argument to be a standard
character (see *note STANDARD-CHAR-P::).

Char-downcase is a Common Lisp function.  See any Common Lisp
documentation for more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: CHAR-EQUAL,  Next: CHAR-UPCASE,  Prev: CHAR-DOWNCASE,  Up: ACL2-BUILT-INS

CHAR-EQUAL    character equality without regard to case

For characters x and y, (char-equal x y) is true if and only if x and y
are the same except perhaps for their case.

The guard on char-equal requires that its arguments are both standard
characters (see *note STANDARD-CHAR-P::).

Char-equal is a Common Lisp function.  See any Common Lisp
documentation for more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: CHAR-UPCASE,  Next: CHAR<,  Prev: CHAR-EQUAL,  Up: ACL2-BUILT-INS

CHAR-UPCASE    turn lower-case characters into upper-case characters

(Char-upcase x) is equal to #\A when x is #\a, #\B when x is #\b, ...,
and #\Z when x is #\z, and is x for any other character.

The guard for char-upcase requires its argument to be a standard
character (see *note STANDARD-CHAR-P::).

Char-upcase is a Common Lisp function.  See any Common Lisp
documentation for more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: CHAR<,  Next: CHAR<=,  Prev: CHAR-UPCASE,  Up: ACL2-BUILT-INS

CHAR<    less-than test for characters

(char< x y) is true if and only if the character code of x is less than
that of y.  See *note CHAR-CODE::.

The guard for char< specifies that its arguments are characters.

Char< is a Common Lisp function.  See any Common Lisp documentation for
more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: CHAR<=,  Next: CHAR>,  Prev: CHAR<,  Up: ACL2-BUILT-INS

CHAR<=    less-than-or-equal test for characters

(char<= x y) is true if and only if the character code of x is less
than or equal to that of y.  See *note CHAR-CODE::.

The guard for char<= specifies that its arguments are characters.

Char<= is a Common Lisp function.  See any Common Lisp documentation
for more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: CHAR>,  Next: CHAR>=,  Prev: CHAR<=,  Up: ACL2-BUILT-INS

CHAR>    greater-than test for characters

(char> x y) is true if and only if the character code of x is greater
than that of y.  See *note CHAR-CODE::.

The guard for char> specifies that its arguments are characters.

Char> is a Common Lisp function.  See any Common Lisp documentation for
more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: CHAR>=,  Next: CHARACTER-ALISTP,  Prev: CHAR>,  Up: ACL2-BUILT-INS

CHAR>=    greater-than-or-equal test for characters

(char>= x y) is true if and only if the character code of x is greater
than or equal to that of y.  See *note CHAR-CODE::.

The guard for char>= specifies that its arguments are characters.

Char>= is a Common Lisp function.  See any Common Lisp documentation
for more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: CHARACTER-ALISTP,  Next: CHARACTER-LISTP,  Prev: CHAR>=,  Up: ACL2-BUILT-INS

CHARACTER-ALISTP    recognizer for association lists with characters as keys

(Character-alistp x) is true if and only if x is a list of pairs of the
form (cons key val) where key is a characterp.


File: acl2-doc-emacs.info,  Node: CHARACTER-LISTP,  Next: CHARACTERP,  Prev: CHARACTER-ALISTP,  Up: ACL2-BUILT-INS

CHARACTER-LISTP    recognizer for a true list of characters

The predicate character-listp tests whether its argument is a true list
of characters.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: CHARACTERP,  Next: CHARACTERS,  Prev: CHARACTER-LISTP,  Up: ACL2-BUILT-INS

CHARACTERP    recognizer for characters

(characterp x) is true if and only if x is a character.


File: acl2-doc-emacs.info,  Node: CHARACTERS,  Next: CHECK-SUM,  Prev: CHARACTERP,  Up: ACL2-BUILT-INS

CHARACTERS    characters in ACL2

ACL2 accepts 256 distinct characters, which are the characters obtained
by applying the function code-char to each integer from 0 to 255.
Among these, Common Lisp designates certain ones as _standard
characters_, namely those of the form (code-char n) where n is from 33
to 126, together with #\Newline and #\Space.  The actual standard
characters may be viewed by evaluating the defconst *standard-chars*.

To be more precise, Common Lisp does not specify the precise
relationship between code-char and the standard characters.  However,
we check that the underlying Common Lisp implementation uses a
particular relationship that extends the usual ASCII coding of
characters.  We also check that Space, Tab, Newline, Page, and Rubout
correspond to characters with respective char-codes 32, 9, 10, 12, and
127.

Code-char has an inverse, char-code.  Thus, when char-code is applied
to an ACL2 character, c, it returns a number n between 0 and 255
inclusive such that (code-char n) = c.

The preceding paragraph implies that there is only one ACL2 character
with a given character code.  CLTL allows for "attributes" for
characters, which could allow distinct characters with the same code,
but ACL2 does not allow this.

_The Character Reader_

ACL2 supports the `#\' notation for characters provided by Common Lisp,
with some restrictions.  First of all, for every character c, the
notation

     #\c

may be used to denote the character object c.  That is, the user may
type in this notation and ACL2 will read it as denoting the character
object c.  In this case, the character immediately following c must be
one of the following "terminating characters": a Tab, a Newline, a Page
character, a space, or one of the characters:

     "  '  (  )  ;  `  ,

Other than the notation above, ACL2 accepts alternate notation for five
characters.

     #\Space
     #\Tab
     #\Newline
     #\Page
     #\Rubout

Again, in each of these cases the next character must be from among the
set of "terminating characters" described in the single-character case.
Our implementation is consistent with IS0-8859, even though we don't
provide #\ syntax for entering characters other than that described
above.

Finally, we note that it is our intention that any object printed by
ACL2's top-level-loop may be read back into ACL2.  Please notify the
implementors if you find a counterexample to this claim.


File: acl2-doc-emacs.info,  Node: CHECK-SUM,  Next: CLOSE-INPUT-CHANNEL,  Prev: CHARACTERS,  Up: ACL2-BUILT-INS

CHECK-SUM    assigning "often unique" integers to files and objects

A "check sum" is an integer in some fixed range computed from the
printed representation of an object, e.g., the sum, modulo 2**32, of
the ascii codes of all the characters in the printed representation.

Ideally, you would like the check sum of an object to be uniquely
associated with that object, like a fingerprint.  It could then be used
as a convenient way to recognize the object in the future: you could
remember the check sum (which is relatively small) and when an object
is presented to you and alleged to be the special one you could compute
its check sum and see if indeed it was.  Alas, there are many more
objects than check sums (after all, each check sum is an object, and
then there's t).  So you try to design a check sum algorithm that maps
similar looking objects far apart, in the hopes that corruptions and
counterfeits -- which appear to be similar to the object -- have
different check sums.  Nevertheless, the best you can do is a
many-to-one map.  If an object with a different check sum is presented,
you can be positive it is not the special object.  But if an object
with the same check sum is presented, you have no grounds for positive
identification.

The basic check sum algorithm in ACL2 is called check-sum-obj, which
computes the check sum of an ACL2 object.  Roughly speaking, we scan
the print representation of the object and, for each character
encountered, we multiply the ascii code of the character times its
position in the stream (modulo a certain prime) and then add (modulo a
certain prime) that into the running sum.  This is inaccurate in many
senses (for example, we don't always use the ascii code and we see
numbers as though they were printed in base 127) but indicates the
basic idea.

ACL2 uses check sums to increase security in the books mechanism; see
*note CERTIFICATE::.


File: acl2-doc-emacs.info,  Node: CLOSE-INPUT-CHANNEL,  Next: CLOSE-OUTPUT-CHANNEL,  Prev: CHECK-SUM,  Up: ACL2-BUILT-INS

CLOSE-INPUT-CHANNEL    See *note IO::.


File: acl2-doc-emacs.info,  Node: CLOSE-OUTPUT-CHANNEL,  Next: CODE-CHAR,  Prev: CLOSE-INPUT-CHANNEL,  Up: ACL2-BUILT-INS

CLOSE-OUTPUT-CHANNEL    See *note IO::.


File: acl2-doc-emacs.info,  Node: CODE-CHAR,  Next: COERCE,  Prev: CLOSE-OUTPUT-CHANNEL,  Up: ACL2-BUILT-INS

CODE-CHAR    the character corresponding to a given numeric code

Completion Axiom (completion-of-code-char):

     (equal (code-char x)
            (if (and (integerp x)
                     (>= x 0)
                     (< x 256))
                (code-char x)
              (code-char 0)))

Guard for (code-char x):

     (and (integerp x)
          (>= x 0)
          (< x 256))

ACL2 supports 8-bit characters.  Inputs not between 0 and 255 are
treated as 0.


File: acl2-doc-emacs.info,  Node: COERCE,  Next: COMPLEX,  Prev: CODE-CHAR,  Up: ACL2-BUILT-INS

COERCE    coerce a character list to a string and a string to a list

Completion Axiom (completion-of-coerce):

     (equal (coerce x y)
            (cond
             ((equal y 'list)
              (if (stringp x)
                  (coerce x 'list)
                nil))
             (t
              (coerce (make-character-list x) 'string))))

Guard for (coerce x y):

     (if (equal y 'list)
         (stringp x)
       (if (equal y 'string)
           (character-listp x)
         nil))

Also see community book books/misc/fast-coerce.lisp, contributed by
Jared Davis, for a version of coerce that may be faster for Common Lisp
implementations other than CCL 1.3 or later, if the second argument is
'list (for coercing a string to a list).


File: acl2-doc-emacs.info,  Node: COMPLEX,  Next: COMPLEX-RATIONALP,  Prev: COERCE,  Up: ACL2-BUILT-INS

COMPLEX    create an ACL2 number

     Examples:
     (complex x 3) ; x + 3i, where i is the principal square root of -1
     (complex x y) ; x + yi
     (complex x 0) ; same as x, for rational numbers x

The function complex takes two rational number arguments and returns an
ACL2 number.  This number will be of type (complex rational) [as
defined in the Common Lisp language], except that if the second
argument is zero, then complex returns its first argument.  The
function complex-rationalp is a recognizer for complex rational
numbers, i.e. for ACL2 numbers that are not rational numbers.

The reader macro #C (which is the same as #c) provides a convenient way
for typing in complex numbers.  For explicit rational numbers x and y,
#C(x y) is read to the same value as (complex x y).

The functions realpart and imagpart return the real and imaginary parts
(respectively) of a complex (possibly rational) number.  So for
example, (realpart #C(3 4)) = 3, (imagpart #C(3 4)) = 4, (realpart 3/4)
= 3/4, and (imagpart 3/4) = 0.

The following built-in axiom may be useful for reasoning about complex
numbers.

     (defaxiom complex-definition
       (implies (and (real/rationalp x)
                     (real/rationalp y))
                (equal (complex x y)
                       (+ x (* #c(0 1) y))))
       :rule-classes nil)

A completion axiom that shows what complex returns on arguments
violating its guard (which says that both arguments are rational
numbers) is the following, named completion-of-complex.

     (equal (complex x y)
            (complex (if (rationalp x) x 0)
                     (if (rationalp y) y 0)))


File: acl2-doc-emacs.info,  Node: COMPLEX-RATIONALP,  Next: COMPLEX/COMPLEX-RATIONALP,  Prev: COMPLEX,  Up: ACL2-BUILT-INS

COMPLEX-RATIONALP    recognizes complex rational numbers

     Examples:
     (complex-rationalp 3)       ; nil, as 3 is rational, not complex rational
     (complex-rationalp #c(3 0)) ; nil, since #c(3 0) is the same as 3
     (complex-rationalp t)       ; nil
     (complex-rationalp #c(3 1)) ; t, as #c(3 1) is the complex number 3 + i

See *note COMPLEX:: for more about complex rationals in ACL2.


File: acl2-doc-emacs.info,  Node: COMPLEX/COMPLEX-RATIONALP,  Next: CONCATENATE,  Prev: COMPLEX-RATIONALP,  Up: ACL2-BUILT-INS

COMPLEX/COMPLEX-RATIONALP    recognizer for complex numbers

For most ACL2 users, this is a macro abbreviating complex-rationalp;
see *note COMPLEX-RATIONALP::.  In ACL2(r) (see *note REAL::), a
complex number x may have irrational real and imaginary parts.  This
macro abbreviates the predicate complexp in ACL2(r), which holds for
such x.  Most ACL2 users can ignore this macro and use
complex-rationalp instead.  Some community books use
complex/complex-rationalp so that they are suitable for ACL2(r) as well.


File: acl2-doc-emacs.info,  Node: CONCATENATE,  Next: COND,  Prev: COMPLEX/COMPLEX-RATIONALP,  Up: ACL2-BUILT-INS

CONCATENATE    concatenate lists or strings together

     Examples:
     (concatenate 'string "ab" "cd" "ef")     ; equals "abcdef"
     (concatenate 'string "ab")               ; equals "ab"
     (concatenate 'list '(a b) '(c d) '(e f)) ; equals '(a b c d e f)
     (concatenate 'list)                      ; equals nil

     General Form:
     (concatenate result-type x1 x2 ... xn)

where n >= 0 and either:  result-type is 'string and each xi is a
string; or result-type is 'list and each xi is a true list.
Concatenate simply concatenates its arguments to form the result string
or list.  Also see *note APPEND:: and see *note STRING-APPEND::.  (The
latter immediately generates a call to concatenate when applied to
strings.)

Note:  We do *not* try to comply with the Lisp language's insistence
that concatenate copies its arguments.  Not only are we in an
applicative setting, where this issue shouldn't matter for the logic,
but also we do not actually modify the underlying lisp implementation
of concatenate; we merely provide a definition for it.

Concatenate is a Common Lisp function.  See any Common Lisp
documentation for more information.


File: acl2-doc-emacs.info,  Node: COND,  Next: CONJUGATE,  Prev: CONCATENATE,  Up: ACL2-BUILT-INS

COND    conditional based on if-then-else

Cond is the construct for IF, THEN, ELSE IF, ...  The test is against
nil.  The argument list for cond is a list of "clauses", each of which
is a list.  In ACL2, clauses must have length 1 or 2.

Cond is a Common Lisp macro.  See any Common Lisp documentation for
more information.


File: acl2-doc-emacs.info,  Node: CONJUGATE,  Next: CONS,  Prev: COND,  Up: ACL2-BUILT-INS

CONJUGATE    complex number conjugate

Conjugate takes an ACL2 number as an argument, and returns its complex
conjugate (i.e., the result of negating its imaginary part.).

Conjugate is a Common Lisp function.  See any Common Lisp documentation
for more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: CONS,  Next: CONSP,  Prev: CONJUGATE,  Up: ACL2-BUILT-INS

CONS    pair and list constructor

(cons x y) is a pair whose first component is x and second component is
y.  If y is a list, then (cons x y) is a list that has an addtional
element x on the front.


File: acl2-doc-emacs.info,  Node: CONSP,  Next: COUNT,  Prev: CONS,  Up: ACL2-BUILT-INS

CONSP    recognizer for cons pairs

(consp x) is true if and only if x is a cons pair.


File: acl2-doc-emacs.info,  Node: COUNT,  Next: CPU-CORE-COUNT,  Prev: CONSP,  Up: ACL2-BUILT-INS

COUNT    count the number of occurrences of an item in a string or true-list

     Example Forms:
     (count #\D "DabcDefcDe")                 ; = 3
     (count #\D "DabcDefcDe" :start 1)        ; = 2
     (count #\D "DabcDefcDe" :start 1 :end 5) ; = 1
     (count #\D "DabcDefcDe" :start 1 :end 4) ; = 0
     (count #\z "DabcDefcDe")                 ; = 0
     (count '(a b) '(17 (a b) 23 (a b) (c d)))   ; = 2

     General Form:
     (count item sequence &key start end)

(Count item sequence) returns the number of times item occurs in
sequence.  The guard for calls of count (which is actually a macro in
ACL2) specifies that sequence is a string or a true-list, and that
start, which defaults to 0, and end, which defaults to the length of
sequence, are valid indices into sequence.

See any Common Lisp documentation for more information about count,
which is a Common Lisp utility.  At this time ACL2 does not support
keyword arguments for count other than :start and :end; we may add
support for the :from-end keyword upon request.


File: acl2-doc-emacs.info,  Node: CPU-CORE-COUNT,  Next: CW,  Prev: COUNT,  Up: ACL2-BUILT-INS

CPU-CORE-COUNT    the number of cpu cores

This documentation topic relates to the experimental extension of ACL2
supporting parallel execution and proof; see *note PARALLELISM::.

Unless the ACL2 executable supports parallel execution (see *note
PARALLELISM::), this function returns (mv 1 state).  Otherwise:

(Cpu-core-count state) returns (mv core-count state), where core-count
is the number of cpu cores if ACL2 can get that information from the
underlying Common Lisp implementation.  Otherwise an error occurs,
unless global 'cpu-core-count is assigned to a positive integer value
(see *note ASSIGN::), in which case that value is returned as the
core-count.

     Example:
     (cpu-core-count state) ==> (mv 4 state)
.


File: acl2-doc-emacs.info,  Node: CW,  Next: CW!,  Prev: CPU-CORE-COUNT,  Up: ACL2-BUILT-INS

CW    print to the comment window

Example:

     (cw "The goal is ~p0 and the alist is ~x1.~%"
         (untranslate term t nil)
         unify-subst)

Logically, this expression is equivalent to nil.  However, it has the
effect of first printing to the so-called "comment window" the fmt
string as indicated.  Thus, cw is like fmt (see *note FMT::) except in
three important ways.  First, it is a macro whose calls expand to calls
of a :logic mode function.  Second, it neither takes nor returns the
ACL2 state; logically cw simply returns nil, although it prints to a
_comment window_ that just happens to share the terminal screen with
the standard character output *standard-co*.  Third, its fmt args are
positional references, so that for example

     (cw "Answers: ~p0 and ~p1" ans1 ans2)

prints in the same manner as:

     (fmt "Answers: ~p0 and ~p1"
          (list (cons #\0 ans1) (cons #\1 ans2))
          *standard-co* state nil)

Typically, calls of cw are embedded in prog2$ forms, e.g.,

     (prog2$ (cw ...)
             (mv a b c))

which has the side-effect of printing to the comment window and
logically returning (mv a b c).

     General Form:
     (cw fmt-string arg1 arg2 ... argn)

where n is between 0 and 9 (inclusive).  The macro uses
fmt-to-comment-window, passing it the column 0 and evisc-tuple nil,
after assembling the appropriate alist binding the fmt vars #\0 through
#\9; see *note FMT::.  If you want

     (a) more than 10 vars,
     (b) vars other than the digit chars,
     (c) a different column, or
     (d) a different evisc-tuple,

then call fmt-to-comment-window instead.

Also see *note CW!::, which is useful if you want to be able to read
the printed forms back in.

Finally, we discuss another way to create formatted output that also
avoids the need to pass in the ACL2 state.  The idea is to use
wormholes; see *note WORMHOLE::.  Below is a function you can write,
along with some calls, providing an illustration of this approach.

     (defun my-fmt-to-comment-window (str alist)
       (wormhole 'my-fmt-to-comment-window
                 '(lambda (whs) whs)
                 (list str alist)
                 '(pprogn
                   (fms (car (@ wormhole-input))
                        (cadr (@ wormhole-input))
                        *standard-co*
                        state
                        nil)
                   (value :q))
                 :ld-verbose nil
                 :ld-error-action :return ; harmless return on error
                 :ld-prompt nil))

     ; A non-erroneous call:
     (my-fmt-to-comment-window "Here is ~x0 for your inspection~%"
                               (list (cons #\0 'foo)))

     ; An error inside the fmt string (unbound fmt var); note that even
     ; with the error, the wormhole is exited.
     (my-fmt-to-comment-window "Here is ~x1 for your inspection~%"
                               (list (cons #\0 'foo)))

     ; A guard violation in the binding; note that even with the error,
     ; the wormhole is exited.
     (my-fmt-to-comment-window "Here is ~x0 for your inspection~%"
                               (list (cons #\0 (car 'foo))))


File: acl2-doc-emacs.info,  Node: CW!,  Next: DELETE-ASSOC,  Prev: CW,  Up: ACL2-BUILT-INS

CW!    print to the comment window

This is the same as cw, except that cw inserts backslash (\) characters
when forced to print past the right margin, in order to make the output
a bit clearer in that case.  Use cw! instead if you want to be able to
read the forms back in.


File: acl2-doc-emacs.info,  Node: DELETE-ASSOC,  Next: DELETE-ASSOC-EQ,  Prev: CW!,  Up: ACL2-BUILT-INS

DELETE-ASSOC    remove the first pair from an association list for a given key

     General Forms:
     (delete-assoc key alist)
     (delete-assoc key alist :test 'eql)   ; same as above (eql as equality test)
     (delete-assoc key alist :test 'eq)    ; same, but eq is equality test
     (delete-assoc key alist :test 'equal) ; same, but equal is equality test

(Delete-assoc key alist) returns an alist that is the same as the list
alist, except that the first pair in alist with a car of key is
deleted, if there is one; otherwise alist is returned.  Note that the
order of the elements of alist is unchanged (though one may be deleted).

The guard for a call of delete-assoc depends on the test.  In all
cases, the second argument must satisfy alistp.  If the test is eql,
then either the first argument must be suitable for eql (see *note
EQLABLEP::) or the second argument must satisfy eqlable-alistp.  If the
test is eq, then either the first argument must be a symbol or the
second argument must satisfy symbol-alistp.

See *note EQUALITY-VARIANTS:: for a discussion of the relation between
delete-assoc and its variants:

     (delete-assoc-eq key alist) is equivalent to (delete-assoc key
     alist :test 'eq);

     (delete-assoc-equal key alist) is equivalent to (delete-assoc key
     alist :test 'equal).


In particular, reasoning about any of these primitives reduces to
reasoning about the function delete-assoc-equal.


File: acl2-doc-emacs.info,  Node: DELETE-ASSOC-EQ,  Next: DELETE-ASSOC-EQUAL,  Prev: DELETE-ASSOC,  Up: ACL2-BUILT-INS

DELETE-ASSOC-EQ    See *note DELETE-ASSOC::.


File: acl2-doc-emacs.info,  Node: DELETE-ASSOC-EQUAL,  Next: DENOMINATOR,  Prev: DELETE-ASSOC-EQ,  Up: ACL2-BUILT-INS

DELETE-ASSOC-EQUAL    See *note DELETE-ASSOC::.


File: acl2-doc-emacs.info,  Node: DENOMINATOR,  Next: DIGIT-CHAR-P,  Prev: DELETE-ASSOC-EQUAL,  Up: ACL2-BUILT-INS

DENOMINATOR    divisor of a ratio in lowest terms

Completion Axiom (completion-of-denominator):

     (equal (denominator x)
            (if (rationalp x)
                (denominator x)
              1))

Guard for (denominator x):

     (rationalp x)


File: acl2-doc-emacs.info,  Node: DIGIT-CHAR-P,  Next: DIGIT-TO-CHAR,  Prev: DENOMINATOR,  Up: ACL2-BUILT-INS

DIGIT-CHAR-P    the number, if any, corresponding to a given character

(digit-char-p ch) is the integer corresponding to the character ch in
base 10.  For example, (digit-char-p #\3) is equal to the integer 3.
More generally, an optional second argument specifies the radix
(default 10, as indicated above).

The guard for digit-char-p (more precisely, for the function
our-digit-char-p that calls of this macro expand to) requires its
second argument to be an integer between 2 and 36, inclusive, and its
first argument to be a character.

Digit-char-p is a Common Lisp function, though it is implemented in the
ACL2 logic as an ACL2 macro.  See any Common Lisp documentation for
more information.


File: acl2-doc-emacs.info,  Node: DIGIT-TO-CHAR,  Next: E0-ORD-<,  Prev: DIGIT-CHAR-P,  Up: ACL2-BUILT-INS

DIGIT-TO-CHAR    map a digit to a character

     Example:
     ACL2 !>(digit-to-char 8)
     #\8

For an integer n from 0 to 15, (digit-to-char n) is the character
corresponding to n in hex notation, using uppercase letters for digits
exceeding 9.  If n is in the appropriate range, that result is of course
also the binary, octal, and decimal digit.

The guard for digit-to-char requires its argument to be an integer
between 0 and 15, inclusive.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: E0-ORD-<,  Next: E0-ORDINALP,  Prev: DIGIT-TO-CHAR,  Up: ACL2-BUILT-INS

E0-ORD-<    the old ordering function for ACL2 ordinals

See *note O<:: for the current new ordering function for ACL2 ordinals.

The functions e0-ordinalp and e0-ord-< were replaced in ACL2
Version_2.8 by o-p and o<, respectively.  However, books created before
that version used the earlier functions for termination proofs; the old
functions might be of use in these cases.  To use the old functions in
termination proofs, include the community book books/ordinals/e0-ordinal
and execute the event (set-well-founded-relation e0-ord-<) (see *note
SET-WELL-FOUNDED-RELATION::).  For a more thorough discussion of these
functions, see the documentation at the end of community book
books/ordinals/e0-ordinal.lisp.


File: acl2-doc-emacs.info,  Node: E0-ORDINALP,  Next: EC-CALL,  Prev: E0-ORD-<,  Up: ACL2-BUILT-INS

E0-ORDINALP    the old recognizer for ACL2 ordinals

See *note O-P:: for the current recognizer for ACL2 ordinals.

The functions e0-ordinalp and e0-ord-< were replaced in ACL2
Version_2.8 by o-p and o<, respectively.  However, books created before
that version used the earlier functions for termination proofs; the old
functions might be of use in these cases.  To use the old functions in
termination proofs, include the community book books/ordinals/e0-ordinal
and execute the event (set-well-founded-relation e0-ord-<) (see *note
SET-WELL-FOUNDED-RELATION::).  For a more thorough discussion of these
functions, see the documentation at the end of community book
books/ordinals/e0-ordinal.lisp.


File: acl2-doc-emacs.info,  Node: EC-CALL,  Next: EIGHTH,  Prev: E0-ORDINALP,  Up: ACL2-BUILT-INS

EC-CALL    execute a call in the ACL2 logic instead of raw Lisp

The name "ec-call" represents "executable-counterpart call."  This
utility is intended for users who are familiar with guards.  See *note
GUARD:: for a general discussion of guards.

Logically, ec-call behaves like the identity macro; during proofs,
(ec-call TERM) is typically replaced quickly by TERM during a proof
attempt.  However, ec-call causes function calls to be evaluated in the
ACL2 logic rather than raw Lisp, as explained below.

     General Form:
     (ec-call (fn term1 ... termk))

where fn is a known function symbol other than those in the list that is
the value of the constant *ec-call-bad-ops*.  In particular, fn is not
a macro.  Semantically, (ec-call (fn term1 ... termk)) equals (fn term1
... termk).  However, this use of ec-call has two effects.

     (1) Guard verification generates no proof obligations from the
     guard of fn for this call.  Indeed, guards need not have been
     verified for fn.

     (2) During evaluation, after the arguments of fn are evaluated as
     usual, the executable counterpart of fn is called, rather than fn
     as defined in raw Lisp.  That is, the call of fn is made on its
     evaluated arguments as though this call is being made in the ACL2
     top-level loop, rather than in raw Lisp.  In particular, the guard
     of fn is checked, at least by default (see *note
     SET-GUARD-CHECKING::).

Note that in the term (ec-call (fn term1 ... termk)), only the indicated
call of fn is made in the logic; each termi is evaluated in the normal
manner.  If you want an entire term evaluated in the logic, wrap
ec-call around each function call in the term (other than calls of if
and ec-call).

*Technical Remark* (probably best ignored).  During evaluation of a call
of defconst or defpkg in raw Lisp, a form (ec-call (fn term1 ...
termk)) is treated as (fn term1 ... termk), that is, without calling
the executable counterpart of fn.  This situation occurs when loading a
compiled file (or expansion file) on behalf of an include-book event.
The reason is technical: executable counterparts are defined below a
book's events in the book's compiled file.  End of Technical Remark.

Here is a small example.  We define foo recursively but with guard
verification inhibited on the recursive call, which is to be evaluated
in the ACL2 logic.

     ACL2 !>(defun foo (x y)
             (declare (xargs :guard (consp y)))
             (if (consp x)
                 (cons (car x) (ec-call (foo (cdr x) (cdr y))))
               (car y)))

     The admission of FOO is trivial, using the relation O< (which is known
     to be well-founded on the domain recognized by O-P) and the measure
     (ACL2-COUNT X).  We could deduce no constraints on the type of FOO.

     Computing the guard conjecture for FOO....

     The guard conjecture for FOO is trivial to prove.  FOO is compliant
     with Common Lisp.

     Summary
     Form:  ( DEFUN FOO ...)
     Rules: NIL
     Warnings:  None
     Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
      FOO
     ACL2 !>(foo '(2 3 4 5) '(6 7))


     ACL2 Error in TOP-LEVEL:  The guard for the function call (FOO X Y),
     which is (CONSP Y), is violated by the arguments in the call
     (FOO '(4 5) NIL).  To debug see :DOC print-gv, see :DOC trace, and
     see :DOC wet.  See :DOC set-guard-checking for information about suppressing
     this check with (set-guard-checking :none), as recommended for new
     users.

     ACL2 !>

The error above arises because eventually, foo recurs down to a value of
parameter y that violates the guard.  This is clear from tracing (see
*note TRACE$:: and see *note TRACE::).  Each call of the executable
counterpart of foo (the so-called "*1*" function for foo) checks the
guard and then invokes the raw Lisp version of foo.  The raw Lisp
version calls the executable counterpart on the recursive call.  When
the guard check fails we get a violation.

     ACL2 !>(trace$ foo)
      ((FOO))
     ACL2 !>(foo '(2 3 4 5) '(6 7))
     1> (ACL2_*1*_ACL2::FOO (2 3 4 5) (6 7))
       2> (FOO (2 3 4 5) (6 7))
         3> (ACL2_*1*_ACL2::FOO (3 4 5) (7))
           4> (FOO (3 4 5) (7))
             5> (ACL2_*1*_ACL2::FOO (4 5) NIL)


     ACL2 Error in TOP-LEVEL:  The guard for the function call (FOO X Y),
     which is (CONSP Y), is violated by the arguments in the call
     (FOO '(4 5) NIL).  To debug see :DOC print-gv, see :DOC trace, and
     see :DOC wet.  See :DOC set-guard-checking for information about suppressing
     this check with (set-guard-checking :none), as recommended for new
     users.

     ACL2 !>

If we turn off guard errors then we can see the trace as above, but
where we avoid calling the raw Lisp function when the guard fails to
hold.

     ACL2 !>:set-guard-checking nil

     Masking guard violations but still checking guards except for self-
     recursive calls.  To avoid guard checking entirely, :SET-GUARD-CHECKING
     :NONE.  See :DOC set-guard-checking.

     ACL2 >(foo '(2 3 4 5) '(6 7))
     1> (ACL2_*1*_ACL2::FOO (2 3 4 5) (6 7))
       2> (FOO (2 3 4 5) (6 7))
         3> (ACL2_*1*_ACL2::FOO (3 4 5) (7))
           4> (FOO (3 4 5) (7))
             5> (ACL2_*1*_ACL2::FOO (4 5) NIL)
               6> (ACL2_*1*_ACL2::FOO (5) NIL)
                 7> (ACL2_*1*_ACL2::FOO NIL NIL)
                 <7 (ACL2_*1*_ACL2::FOO NIL)
               <6 (ACL2_*1*_ACL2::FOO (5))
             <5 (ACL2_*1*_ACL2::FOO (4 5))
           <4 (FOO (3 4 5))
         <3 (ACL2_*1*_ACL2::FOO (3 4 5))
       <2 (FOO (2 3 4 5))
     <1 (ACL2_*1*_ACL2::FOO (2 3 4 5))
     (2 3 4 5)
     ACL2 >


File: acl2-doc-emacs.info,  Node: EIGHTH,  Next: ENDP,  Prev: EC-CALL,  Up: ACL2-BUILT-INS

EIGHTH    eighth member of the list

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: ENDP,  Next: EQ,  Prev: EIGHTH,  Up: ACL2-BUILT-INS

ENDP    recognizer for empty lists

In the ACL2 logic, (endp x) is the same as (atom x).  See *note ATOM::.

Unlike atom, the guard for endp requires that x is a cons pair or is
nil.  Thus, endp is typically used as a termination test for functions
that recur on a true-listp argument.  See *note GUARD:: for general
information about guards.

Endp is a Common Lisp function.  See any Common Lisp documentation for
more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: EQ,  Next: EQL,  Prev: ENDP,  Up: ACL2-BUILT-INS

EQ    equality of symbols

Eq is the function for determining whether two objects are identical
(i.e., have the exact same store address in the current von Neumann
implementation of Common Lisp).  It is the same as equal in the ACL2
logic.

Eq is a Common Lisp function.  In order to ensure conformance with
Common Lisp, the ACL2 guard on eq requires at least one of the
arguments to eq to be a symbol.  Common Lisp guarantees that if x is a
symbol, then x is eq to y if and only if x is equal to y.  Thus, the
ACL2 user should think of eq as nothing besides a fast means for
checking equal when one argument is known to be a symbol.  In
particular, it is possible that an eq test will not even require the
cost of a function call but will be as fast as a single machine
instruction.


File: acl2-doc-emacs.info,  Node: EQL,  Next: EQLABLE-ALISTP,  Prev: EQ,  Up: ACL2-BUILT-INS

EQL    test equality (of two numbers, symbols, or characters)

(eql x y) is logically equivalent to (equal x y).

Unlike equal, eql has a guard requiring at least one of its arguments
to be a number, a symbol, or a character.  Generally, eql is executed
more efficiently than equal.

For a discussion of the various ways to test against 0, See *note
ZERO-TEST-IDIOMS::.

Eql is a Common Lisp function.  See any Common Lisp documentation for
more information.


File: acl2-doc-emacs.info,  Node: EQLABLE-ALISTP,  Next: EQLABLE-LISTP,  Prev: EQL,  Up: ACL2-BUILT-INS

EQLABLE-ALISTP    recognizer for a true list of pairs whose cars are suitable for eql

The predicate eqlable-alistp tests whether its argument is a true-listp
of consp objects whose cars all satisfy eqlablep.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: EQLABLE-LISTP,  Next: EQLABLEP,  Prev: EQLABLE-ALISTP,  Up: ACL2-BUILT-INS

EQLABLE-LISTP    recognizer for a true list of objects each suitable for eql

The predicate eqlable-listp tests whether its argument is a true-listp
of objects satisfying eqlablep.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: EQLABLEP,  Next: EQUAL,  Prev: EQLABLE-LISTP,  Up: ACL2-BUILT-INS

EQLABLEP    the guard for the function eql

The predicate eqlablep tests whether its argument is suitable for eql,
at least one of whose arguments must satisfy this predicate in Common
Lisp.  (Eqlablep x) is true if and only if its argument is a number, a
symbol, or a character.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: EQUAL,  Next: ER,  Prev: EQLABLEP,  Up: ACL2-BUILT-INS

EQUAL    true equality

(equal x y) is equal to t or nil, according to whether or not x and y
are the same value.

For a discussion of the various idioms for testing against 0, See *note
ZERO-TEST-IDIOMS::.


File: acl2-doc-emacs.info,  Node: ER,  Next: ER-PROGN,  Prev: EQUAL,  Up: ACL2-BUILT-INS

ER    print an error message and "cause an error"

See *note FMT:: for a general discussion of formatted printing in ACL2.
All calls of er print formatted strings, just as is done by fmt.

     Example Forms:
     (er hard  'top-level "Illegal inputs, ~x0 and ~x1." a b)
     (er hard? 'top-level "Illegal inputs, ~x0 and ~x1." a b)
     (er soft  'top-level "Illegal inputs, ~x0 and ~x1." a b)

The examples above all print an error message to standard output saying
that a and b are illegal inputs.  However, the first two abort
evaluation after printing an error message (while logically returning
nil, though in ordinary evaluation the return value is never seen);
while the third returns (mv t nil state) after printing an error
message.  The result in the third case can be interpreted as an "error"
when programming with the ACL2 state, something most ACL2 users will
probably not want to do unless they are building systems of some sort;
see *note PROGRAMMING-WITH-STATE::.  If state is not available in the
current context then you will probably want to use (er hard ...) or (er
hard? ...) to cause an error; for example, if you are returning two
values, you may write (mv (er hard ...) nil).

The difference between the hard and hard? forms is one of guards.  Use
hard if you want the call to generate a (clearly impossible) guard
proof obligation of (essentially) NIL.  But use hard? if you want to be
able to call this function in guard-verified code, since the call
generates a (trivially satisfied) guard proof obligation of T.

Er is a macro, and the above three examples expand to calls of ACL2
functions, as shown below.  See *note ILLEGAL::, see *note
HARD-ERROR::, and see *note ERROR1::.  The first two have guards of
(essentially) NIL and T, respectively, while error1 is in :program mode.

     General forms:
     (er hard  ctx fmt-string arg1 arg2 ... argk)
       ==> {macroexpands, in essence, to:}
     (ILLEGAL    CTX FMT-STRING
                 (LIST (CONS #\0 ARG1) (CONS #\1 ARG2) ... (CONS #\k ARGk)))

     (er hard? ctx fmt-string arg1 arg2 ... argk)
       ==> {macroexpands, in essence, to:}
     (HARD-ERROR CTX FMT-STRING
                 (LIST (CONS #\0 ARG1) (CONS #\1 ARG2) ... (CONS #\k ARGk)))

     (er soft  ctx fmt-string arg1 arg2 ... argk)
       ==> {macroexpands, in essence, to:}
     (ERROR1     CTX FMT-STRING
                 (LIST (CONS #\0 ARG1) (CONS #\1 ARG2) ... (CONS #\k ARGk)))


File: acl2-doc-emacs.info,  Node: ER-PROGN,  Next: ERROR1,  Prev: ER,  Up: ACL2-BUILT-INS

ER-PROGN    perform a sequence of state-changing "error triples"

     Example:
     (er-progn (check-good-foo-p (f-get-global 'my-foo state) state)
               (value (* (f-get-global 'my-foo state)
                         (f-get-global 'bar state))))

This sequencing primitive is only useful when programming with state,
something that very few users will probably want to do.  See *note
STATE::.

Er-progn is used much the way that progn is used in Common Lisp, except
that it expects each form within it to evaluate to an "error triple" of
the form (mv erp val state); see *note ERROR-TRIPLES::.  The first such
form, if any, that evaluates to such a triple where erp is not nil
yields the error triple returned by the er-progn.  If there is no such
form, then the last form returns the value of the er-progn form.

     General Form:
     (er-progn <expr1> ... <exprk>)

where each <expri> is an expression that evaluates to an error triple
(see *note PROGRAMMING-WITH-STATE::).  The above form is essentially
equivalent to the following ("essentially" because in fact, care is
taken to avoid variable capture).

     (mv-let (erp val state)
             <expr1>
             (cond (erp (mv erp val state))
                   (t (mv-let (erp val state)
                              <expr2>
                              (cond (erp (mv erp val state))
                                    (t ...
                                           (mv-let (erp val state)
                                                   <expr{k-1}>
                                                   (cond (erp (mv erp val state))
                                                         (t <exprk>)))))))))


File: acl2-doc-emacs.info,  Node: ERROR1,  Next: EVENP,  Prev: ER-PROGN,  Up: ACL2-BUILT-INS

ERROR1    print an error message and cause a "soft error"

(Error1 ctx str alist) returns (mv t nil state).  An error message is
first printed using the the "context" ctx, as well as the string str
and alist alist that are of the same kind as expected by fmt.  See
*note FMT::.

Error1 can be interpreted as causing an "error" when programming with
the ACL2 state, something most ACL2 users will probably not want to do;
see *note LD-ERROR-TRIPLES:: and see *note ER-PROGN::.  In order to
cause errors with :logic mode functions, see *note HARD-ERROR:: and see
*note ILLEGAL::.  Better yet, see *note ER:: for a macro that provides
a unified way of signaling errors.

As mentioned above, error1 always returns (mv t nil state).  But if a
call (error1 ctx str alist) is encountered during evaluation, then the
string str is first printed using the association list alist (as in
fmt).  Here is a trivial, contrived example.

     ACL2 !>(error1 'my-context
                    "Printing 4: ~n0"
                    (list (cons #\0 4))
                    state)


     ACL2 Error in MY-CONTEXT:  Printing 4: four

     ACL2 !>


File: acl2-doc-emacs.info,  Node: EVENP,  Next: EXPLODE-NONNEGATIVE-INTEGER,  Prev: ERROR1,  Up: ACL2-BUILT-INS

EVENP    test whether an integer is even

(evenp x) is true if and only if the integer x is even.  Actually, in
the ACL2 logic (evenp x) is defined to be true when x/2 is an integer.

The guard for evenp requires its argument to be an integer.

Evenp is a Common Lisp function.  See any Common Lisp documentation for
more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: EXPLODE-NONNEGATIVE-INTEGER,  Next: EXPT,  Prev: EVENP,  Up: ACL2-BUILT-INS

EXPLODE-NONNEGATIVE-INTEGER    the list of characters in the radix-r form of a number

     Examples:
     ACL2 !>(explode-nonnegative-integer 925 10 nil)
     (#9 #2 #5)
     ACL2 !>(explode-nonnegative-integer 325 16 nil)
     (#3 #9 #D)

For a non-negative integer n, (explode-nonnegative-integer n r nil) is
the list of characters in the radix-r (base-r) representation of n.

The guard for explode-nonnegative-integer requires the first argument
to be a nonnegative integer and second argument to be a valid radix for
ACL2 (2, 8, 10, or 16).

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: EXPT,  Next: F-GET-GLOBAL,  Prev: EXPLODE-NONNEGATIVE-INTEGER,  Up: ACL2-BUILT-INS

EXPT    exponential function

(Expt r i) is the result of raising the number r to the integer power i.

The guard for (expt r i) is that r is a number and i is an integer, and
furthermore, if r is 0 then i is nonnegative.  When the type
requirements of the guard aren't met, (expt r i) first coerces r to a
number and i to an integer.

Expt is a Common Lisp function.  See any Common Lisp documentation for
more information.  Note that r can be a complex number; this is
consistent with Common lisp.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: F-GET-GLOBAL,  Next: F-PUT-GLOBAL,  Prev: EXPT,  Up: ACL2-BUILT-INS

F-GET-GLOBAL    get the value of a global variable in state

     Examples:
     (+ (f-get-global 'y state) 1)
     (f-put-global 'a
                   (aset1 'ascii-map-array
                          (f-get-global 'a state)
                          66
                          'Upper-case-B)
                   state)

     General Form:
     (f-get-global 'symbol state)

where symbol is any symbol to which you have assigned a global value.

The macro @ is closely related to f-get-global: (@ var) macroexpands to
(f-get-global 'var state).

The macro f-get-global makes it convenient to set the value of a
symbol.  The :ubt operation has no effect on the global-table of state.
Thus, you may use these globals to hang onto useful data structures
even though you may undo back past where you computed and saved them.


File: acl2-doc-emacs.info,  Node: F-PUT-GLOBAL,  Next: FIFTH,  Prev: F-GET-GLOBAL,  Up: ACL2-BUILT-INS

F-PUT-GLOBAL    assign to a global variable in state

     Examples:
     (f-put-global 'x (expt 2 10) state)
     (f-put-global 'a (aset1 'ascii-map-array (@ a) 66 'Upper-case-B) state)

     General Form:
     (f-put-global (quote symbol) term state)

where symbol is any symbol (with certain enforced exclusions to avoid
overwriting ACL2 system "globals") and term is any ACL2 term that could
be evaluated at the top-level.  F-put-global evaluates the term, stores
the result as the value of the given symbol in the global-table of
state, and returns the new state.  (Note:  the actual implementation of
the storage of this value is much more efficient than this discussion
of the logic might suggest.)

The macro assign is closely related to f-put-global: (assign var val)
macroexpands to (f-put-global 'var val state).

The macros @ and f-get-global give convenient access to the value of
such globals.  The :ubt operation has no effect on the global-table of
state.  Thus, you may use these globals to hang onto useful data
structures even though you may undo back past where you computed and
saved them.


File: acl2-doc-emacs.info,  Node: FIFTH,  Next: FIRST,  Prev: F-PUT-GLOBAL,  Up: ACL2-BUILT-INS

FIFTH    fifth member of the list

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: FIRST,  Next: FIX,  Prev: FIFTH,  Up: ACL2-BUILT-INS

FIRST    first member of the list

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: FIX,  Next: FIX-TRUE-LIST,  Prev: FIRST,  Up: ACL2-BUILT-INS

FIX    coerce to a number

Fix simply returns any numeric argument unchanged, returning 0 on a
non-numeric argument.  Also see *note NFIX::, see *note IFIX::, and see
*note RFIX:: for analogous functions that coerce to a natural number,
an integer, and a rational number, respectively.

Fix has a guard of t.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: FIX-TRUE-LIST,  Next: FLET,  Prev: FIX,  Up: ACL2-BUILT-INS

FIX-TRUE-LIST    coerce to a true list

Fix-true-list is the identity function on true-listp objects.  It
converts every list to a true list by dropping the final cdr, and it
converts every atom to nil.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: FLET,  Next: FLOOR,  Prev: FIX-TRUE-LIST,  Up: ACL2-BUILT-INS

FLET    local binding of function symbols

     Example Form:
     ; The following evaluates to (mv 7 10):
     (flet ((f (x)
               (+ x 3))
            (g (x)
               (declare (type integer x))
               (* x 2)))
       (mv (f 4) (g 5)))

     General Forms:
     (flet (def1 ... defk) body)
     (flet (def1 ... defk) declare-form1 .. declare-formk body)

where body is a term, and each defi is a definition as in defun but
with the leading defun symbol omitted.  See *note DEFUN::.  If any
declare-formi are supplied, then each must be of the form (declare
decl1 ... decln), where each decli is of the form (inline g1 ... gm) or
(notinline g1 ... gm), and each gi is defined by some defi.

The only effect of the declarations is to provide advice to the host
Lisp compiler.  The declarations are otherwise ignored by ACL2, so we
mainly ignore them in the discussion below.

The innermost flet-binding of a function symbol, f, above a call of f,
is the one that provides the definition of f for that call.  Note that
flet does not provide recursion.  Consider the following example.

     ; Give a global definition of f:
     (defun f (x) (+ x 3))
     ; Evaluate an expression using a local binding of f:
     (flet ((f (x) (cons x (f (1+ x)))))
       (f 4))

In the above term (cons x (f (1+ x))), f refers to the global
definition of f above the flet expression.  However, (f 4) refers to
the flet-binding of f, (f (x) (cons x (f x))).  The result of the flet
expression is thus obtained by evaluating (f 4) where (f 4) is (cons 4
(f (1+ 4))), where the latter call of f refers to the global
definition; thus we have (cons 4 (f 5)), which evaluates to (4 . 8).

Although flet behaves in ACL2 essentially as it does in Common Lisp,
ACL2 imposes the following restrictions and qualifications.

     o Every declare form for a local definition (def1 through defk,
     above) must be an ignore, ignorable, or type expression.

     o Each defi must bind a different function symbol.

     o Each defi must bind a symbol that is a legal name for an ACL2
     function symbol.  In particular, the symbol may not be in the
     keyword package or the main Lisp package.  Moreover, the symbol
     may not be a built-in ACL2 function or macro.

     o Every variable occurring in the body of a defi must be a formal
     parameter of that defi.  (This restriction is not enforced in
     Common Lisp.  If the restriction is inconvenient for you, the ACL2
     implementors may be able to remove it, with some effort, if you
     ask.)

     o If the flet-binding defi is in the body of a function f, then
     the stobj inputs for defi are implicitly those of its inputs that
     are declared stobj inputs of f.

Flet bindings are evaluated in parallel.  Consider the following
example.

     (defun f (x) x)
     (flet ((f (x) (cons x x))
            (g (x) (f x)))
       (g 3))

The binding of g refers to the global value of f, not the flet-binding
of f.  Thus, the flet expression evaluates to 3.  Compare the flet
expression above to the following one, which instead evaluates to (3 .
3).

     (defun f (x) x)
     (flet ((f (x) (cons x x)))
       (flet ((g (x) (f x)))
         (g 3)))

Under the hood, ACL2 translates flet bindings to lambda expressions
(see *note TERM::), throwing away the inline and notinline declarations
(if any).  The following example illustrates this point.

     ACL2 !>:trans (flet ((f (x) (cons x x))
                          (g (x y) (+ x y)))
                     (declare (inline f))
                     (f (g 3 4)))

     ((LAMBDA (X) (CONS X X))
      ((LAMBDA (X Y) (BINARY-+ X Y)) '3 '4))

     => *

     ACL2 !>

Flet is part of Common Lisp.  See any Common Lisp documentation for
more information.  We conclude by pointing out an important aspect of
flet shared by ACL2 and Common Lisp: The binding is lexical, not
dynamic.  That is, the flet binding of a function symbol only applies to
calls of that function symbol in the body of the flet, not other calls
made in the course of evaluation.  Consider the following example.
Suppose we define:

     (defun f (x) x)
     (defun g (x) x)
     (defun h (x)
       (flet ((f (x) (cons x x)))
         (g x)))

Then evaluation of (h 3) results in 3, not in the cons pair (3 . 3),
because the flet binding of f only applies to calls of f that appear in
the body of that flet.  In this case, only g is called in the body of
that flet.


File: acl2-doc-emacs.info,  Node: FLOOR,  Next: FMS,  Prev: FLET,  Up: ACL2-BUILT-INS

FLOOR    division returning an integer by truncating toward negative infinity

     Example Forms:
     ACL2 !>(floor 14 3)
     4
     ACL2 !>(floor -14 3)
     -5
     ACL2 !>(floor 14 -3)
     -5
     ACL2 !>(floor -14 -3)
     4
     ACL2 !>(floor -15 -3)
     5

(Floor i j) returns the result of taking the quotient of i and j and
returning the greatest integer not exceeding that quotient.  For
example, the quotient of -14 by 3 is -4 2/3, and the largest integer
not exceeding that rational number is -5.

The guard for (floor i j) requires that i and j are rational (real, in
ACL2(r)) numbers and j is non-zero.

Floor is a Common Lisp function.  See any Common Lisp documentation for
more information.  However, note that unlike Common Lisp, the ACL2
floor function returns only a single value,

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: FMS,  Next: FMS!,  Prev: FLOOR,  Up: ACL2-BUILT-INS

FMS    :(str alist co-channel state evisc) => state

See *note FMT:: for further explanation, including documentation of the
tilde-directives.


File: acl2-doc-emacs.info,  Node: FMS!,  Next: FMS!-TO-STRING,  Prev: FMS,  Up: ACL2-BUILT-INS

FMS!    :(str alist co-channel state evisc) => state

This function is nearly identical to fms; see *note FMS::.  The only
difference is that fms may insert backslash (\) characters when forced
to print past the right margin in order to make the output a bit
clearer in that case.  Use fms! instead if you want to be able to read
the forms back in.


File: acl2-doc-emacs.info,  Node: FMS!-TO-STRING,  Next: FMS-TO-STRING,  Prev: FMS!,  Up: ACL2-BUILT-INS

FMS!-TO-STRING    See *note PRINTING-TO-STRINGS::.


File: acl2-doc-emacs.info,  Node: FMS-TO-STRING,  Next: FMT,  Prev: FMS!-TO-STRING,  Up: ACL2-BUILT-INS

FMS-TO-STRING    See *note PRINTING-TO-STRINGS::.


File: acl2-doc-emacs.info,  Node: FMT,  Next: FMT!,  Prev: FMS-TO-STRING,  Up: ACL2-BUILT-INS

FMT    formatted printing

ACL2 provides the functions fmt, fmt1, and fms as substitutes for
Common Lisp's format function.  Also see *note FMT!::, see *note
FMT1!::, and see *note FMS!:: for versions of these functions that
write forms to files in a manner that allows them to be read, by
avoiding using backslash (\) to break long lines.  There are also
analogues of these functions that return a string without taking state
as an argument; see *note PRINTING-TO-STRINGS::.

All three print a given string under an alist pairing character objects
with values, interpreting certain "tilde-directives" in the string.
Channel must be a character output channel (e.g., *standard-co*).

     General Forms:                                            result
     (fms string alist channel state evisc-tuple)         ; state
     (fmt string alist channel state evisc-tuple)         ; (mv col state)
     (fmt1 string alist column channel state evisc-tuple) ; (mv col state)

Fms and fmt print an initial newline to put channel in column 0; Fmt1
requires the current column as input.  Columns are numbered from 0.
The current column is the column into which the next character will be
printed.  (Thus, the current column number is also the number of
characters printed since the last newline.)  The col returned by fmt
and fmt1 is the current column at the conclusion of the formatting.
Evisc-tuple must be either nil (meaning no abbreviations are used when
objects are printed) or an "evisceration tuple"; see *note
EVISC-TUPLE::.

We list the tilde-directives below.  The notation is explained after
the chart.

     ~xx  pretty print vx (maybe after printing a newline)
     ~yx  pretty print vx starting in current column; end with newline
     ~Xxy like ~xx but use vy as the evisceration tuple
     ~Yxy like ~yx but use vy as the evisceration tuple
     ~@x  if vx is a string, "str",  recursively format "str"
          if vx is ("str" . a), recursively format "str" under a+
     ~#x~[...~/...~/ ... ~/...~] cases on vx
          ^    ^     ...   ^  if 0<=vx<=k, choose vxth alternative
          0    1     ...   k  if vx is a list of length 1, case 0; else 1
     ~*x  iterator: vx must be of the form
          ("str0" "str1" "str2" "str3" lst . a);
          if lst is initially empty, format "str0" under a+; otherwise,
          bind #\* successively to the elements of lst and then
          recursively format "stri" under a+, where i=1 if there is one
          element left to process, i=2 if there are two left, and i=3
          otherwise.
     ~&x  print elements of vx with ~x, separated by commas and a
          final ``and''
     ~vx  print elements of vx with ~x, separated by commas and a
          final ``or''
     ~nx  if vx is a small positive integer, print it as a word, e.g.,
          seven;
          if vx is a singleton containing a small positive integer, print
            the corresponding ordinal as a word, e.g., seventh
     ~Nx  like ~nx but the word is capitalized, e.g., Seven or Seventh
     ~tx  tab out to column vx; newline first if at or past column vx
     ~cx  vx is (n . w), print integer n right justified in field of
          width w
     ~fx  print object vx flat over as many lines as necessary
     ~Fx  same as ~f, except that subsequent lines are indented to
          start one character to the right of the first character printed
     ~sx  if vx is a symbol, print vx, breaking on hyphens (unless the
          symbol would normally be printed with surrounding vertical bar
          characters (|), in which case print as with ~fx); if vx is a
          string, print the characters in it, breaking on hyphens; else
          vx is a number, to be printed using the current print-base and
          print-radix
     ~    tilde space: print a space
     ~_x  print vx spaces
     ~
          tilde newline: skip following whitespace
     ~%   output a newline
     ~|   output a newline unless already on left margin
     ~~   print a tilde
     ~-   if close to rightmargin, output a hyphen and newline; else
          skip this char

If x is a character, then vx is the value of #\x under the current
alist.  Consider for example the discussion above for ~y, "~yx  pretty
print vx", applied to the following expression: (fmt "HELLO ~y7" (list
(cons #\7 'world)) *standard-co* state nil).  Then in this example: #\x
is 7; and vx is the value of character #\7 under the given alist, which
is the symbol, WORLD.  Thus, ACL2 will print HELLO WORLD.  When we say
"format str under a+" we mean: process the given string under an alist
obtained by appending a to the current alist.  The following example
illustrates how this works.

     ACL2 !>(fms "~@0"
                 (list (cons #\0 (cons "~x0 ~@1" (list (cons #\0  'abc))))
                       (cons #\1 "-- and now: ~x0 again~%"))
                 *standard-co* state nil)

     ABC -- and now: ABC again
     <state>
     ACL2 !>

Note:  ~p, ~q, ~P, and ~Q are also currently supported, but are
deprecated.  These are respectively the same as ~x, ~y, ~X, and ~Y,
except that their arguments are expected to be terms, preferably
untranslated (user-level) terms, that could be printed using infix
notation in certain environments.  Infix printing is not currently
supported but may be if there is sufficient need for it.

ACL2's formatting functions print to the indicated channel, keeping
track of which column they are in.  Fmt1 can be used if the caller
knows which column the channel is in (i.e., how many characters have
been printed since the last newline).  Otherwise, fmt or fms must be
used, both of which output a newline so as to establish the column
position at 0.  Unlike Common Lisp's format routine, fmt and its
relatives break the output into lines so that, by default, an attempt
is made to avoid printing past column 77 (the value of constant
*fmt-hard-right-margin-default*).  See *note
SET-FMT-HARD-RIGHT-MARGIN:: for a discussion of how linebreaks are
inserted and how to change the relevant default settings.

The formatting functions scan the string from left to right, printing
each successive character unless it is a tilde (~).  Upon encountering
tildes the formatters take action determined by the character or
characters immediately following the tilde.  The typical
tilde-directive is a group of three successive characters from the
string being printed.  For example, ~x0 is a 3 character
tilde-directive.  The first character in a tilde-directive is always
the tilde character itself.  The next character is called the "command"
character.  The character after that is usually taken as the name of a
"format variable" that is bound in the alist under which the string is
being printed.  Format variables are, by necessity, characters.  The
objects actually printed by a tilde-directive are the objects obtained
by looking up the command's format variables in the alist.  Typical
format variable names are 0, 1, 2, ..., 9, a, b, c, etc., and if a
tilde-directive uses the format variable 0, as in ~x0, then the
character #\0 must be bound in the alist.  Some tilde commands take no
arguments and others take more than one, so some directives are of
length two and others are longer.

It should be noted that this use of characters in the string to denote
arguments is another break from Common Lisp's format routine.  In
Common Lisp, the directives refer implicitly to the "next item to be
printed."  But in ACL2 the directives name each item explicitly with
our format variables.

The following text contains examples that can be evaluated.  To make
this process easier, we use a macro which is defined as part of ACL2
just for this documentation.  The macro is named fmx and it takes up to
eleven arguments, the first of which is a format string, str, and the
others of which are taken as the values of format variables.  The
variables used are #\0 through #\9.  The macro constructs an
appropriate alist, a, and then evaluates (fmt str a *standard-co* state
nil).

Thus,

     (fmx "Here is v0, ~x0, and here is v1, ~x1."
          (cons 'value 0)
          (cons 'value 1))

is just an abbreviation for

     (fmt "Here is v0, ~x0, and here is v1, ~x1."
          (list (cons #\0 (cons 'value 0))
                (cons #\1 (cons 'value 1)))
          *standard-co*
          state
          nil)

which returns (mv 53 state) after printing the line

        Here is v0, (VALUE . 0), and here is v1, (VALUE . 1).

We now devote special attention to three of the tilde-directives whose
use is non-obvious.

_The Case Statement_

~#x is essentially a "case statement" in the language of fmt.  The
proper form of the statement is

     ~#x~[case-0~/case-1~/ ... ~/case-k~],

where each of the case-i is a format string.  In the most common use,
the variable x has an integer value, vx, between 0 and k, inclusive.
The effect of formatting the directive is to format case-vx.

For example

     (fmx "Go ~#0~[North~/East~/South~/West~].~%" 1)

will print "Go East." followed by a newline and will return

(mv 0 state), while if you change the 1 above to 3 (the maximum legal
value), it will print "Go West."

In order to make it easier to print such phrases as "there are seven
cases" requiring agreement between subject and verb based on the number
of elements of a list, the case statement allows its variable to take a
list as its value and selects case-0 if the list has length 1 and
case-1 otherwise.

     (let ((cases '(a b c)))
       (fmx "There ~#0~[is ~n1 case~/are ~n1 cases~]."
            cases
            (length cases)))

will print "There are three cases." but if you change the

'(a b c) above simply to '(a) it will print "There is one case." and if
you change it to nil it will print "There are zero cases."

_Indirection_

Roughly speaking, ~@ will act as though the value of its argument is a
format string and splice it into the current string at the current
position.  It is often used when the phrase to be printed must be
computed.  For example,

     (let ((ev 'DEFUN))
      (fmx "~x0 is an event~@1."
           'foo
           (if (member-eq ev '(defun defstub encapsulate))
               " that may introduce a function symbol"
               "")))

will print "foo is an event that may introduce a function symbol," but
if the value of ev is changed from 'defun to 'defthm, it prints "foo is
an event."  The ~@ directive "splices" in the computed phrase (which
might be empty).  Of course, this particular example could be done with
the case statement

     ~#1~[~/ that may introduce a function symbol~]

where the value of #\1 is appropriately computed to be 0 or 1.

If the argument to ~@ is a pair, it is taken to be a format string
consed onto an alist, i.e., ("str" . a), and the alist, a, is used to
extend the current one before "str" is recursively processed.  This
feature of fmt can be used to pass around "phrases" that contain
computed contextual information in a.  The most typical use is as
"error messages."  For example, suppose you are writing a function
which does not have access to state and so cannot print an error
message.  It may nevertheless be necessary for it to signal an error to
its caller, say by returning two results, the first of which is
interpreted as an error message if non-nil.  Our convention is to use a
~@ pair to represent such messages.  For example, the error value might
be produced by the code:

     (cons
       "Error:  The instruction ~x0 is illegal when the stack is ~x1.~%"
       (list (cons #\0 (current-instruction st))
             (cons #\1 (i-stack st))))

If the current-instruction and i-stack (whatever they are) are '(popi
3) and '(a b) when the cons above is evaluated, then it produces

     '("Error:  The instruction ~x0 is illegal when the stack is ~x1.~%"
       (#\0 POPI 3)
       (#\1 A B))

and if this pair is made the value of the fmt variable 0, then ~@0 will
print

        Error:  The instruction (POPI 3) is illegal when the stack is (A B).

For example, evaluate

     (let
      ((pair
       '("Error:  The instruction ~x0 is illegal when the stack is ~x1.~%"
         (#\0 POPI 3)
         (#\1 A B))))
      (fmx "~@0" pair)).

Thus, even though the function that produced the "error" could not
print it, it could specify exactly what error message and data are to
be printed.

This example raises another issue.  Sometimes it is desirable to break
lines in your format strings so as to make your source code more
attractive.  That is the purpose of the tilde-newline directive.  The
following code produces exactly the same output as described above.

     (let ((pair '("Error:  The instruction ~x0 ~
                   is illegal when the stack is ~
                   ~x1.~%"
                   (#\0 POPI 3)
                   (#\1 A B))))
      (fmx "~@0" pair)).

Finally, observe that when ~@0 extends the current alist, alist, with
the one, a, in its argument, the bindings from a are added to the front
of alist, overriding the current values of any shared variables.  This
ensures that the variable values seen by the recursively processed
string, "str", are those from a, but if "str" uses variables not bound
in a, their values are as specified in the original alist.
Intuitively, variables bound in a are local to the processing of ("str"
. a) but "str" may use "global variables."  The example above
illustrates this because when the ~@0 is processed, #\0 is bound to the
error message pair.  But when the ~x0 in the error string is processed,
#\0 is bound to the illegal instruction.

_Iteration_

The ~* directive is used to process each element of a list.  For
example,

     (let ((lst '(a b c d e f g h))) ; a true-list whose elements we exhibit
      (fmx "~*0"
           `("Whoa!"          ; what to print if there's nothing to print
             "~x*!"           ; how to print the last element
             "~x* and "       ; how to print the 2nd to last element
             "~x*, "          ; how to print all other elements
             ,lst)))          ; the list of elements to print

will print "A, B, C, D, E, F, G and H!".  Try this example with other
true list values of lst, such as '(a b), '(a), and nil.  The
tilde-directives ~&0 and ~v0, which take a true list argument and
display its elements separated by commas and a final "and" or "or," are
implemented in terms of the more general ~*.

The ~* directive allows the 5-tuple to specify in its final cdr an
alist with which to extend the current one before processing the
individual elements.

We often use ~* to print a series of phrases, separated by suitable
punctuation, whitespace and noise words.  In such use, the ~* handles
the separation of the phrases and each phrase is generally printed by
~@.

Here is a complex example.  In the let*, below, we bind phrases to a
list of ~@ pairs and then we create a ~* 5-tuple to print out the
conjunction of the phrases with a parenthetical "finally!" if the
series is longer than 3.

     (let* ((phrases
             (list (list "simplifying with the replacement rules ~&0"
                         (cons #\0 '(rewrite-rule1
                                     rewrite-rule2
                                     rewrite-rule3)))
                   (list "destructor elimination using ~x0"
                         (cons #\0 'elim-rule))
                   (list "generalizing the terms ~&0"
                         (cons #\0 '((rev x) (app u v))))
                   (list "inducting on ~x0"
                         (cons #\0 'I))))
            (5-tuple
             (list
              "magic"                            ; no phrases
              "~@*"                              ; last phrase
              "~@*, and~#f~[~/ (finally!)~] "    ; second to last phrase
              "~@*, "                            ; other phrases
              phrases                            ; the phrases themselves
              (cons #\f
                    (if (>(length phrases) 3) 1 0))))) ;print ``finally''?
       (fmx "We did it by ~*0." 5-tuple))

This let* prints

        We did it by simplifying with the replacement rules REWRITE-RULE1,
        REWRITE-RULE2 and REWRITE-RULE3, destructor elimination using ELIM-
        RULE, generalizing the terms (REV X) and (APP U V), and (finally!)
        inducting on I.

You might wish to try evaluating the let* after removing elements of
phrases.

Most of the output produced by ACL2 is produced via fmt statements.
Thus, inspection of the source code will yield many examples.  A
complicated example is the code that explains the simplifier's work.
See :pc simplify-clause-msg1.  An ad hoc example is provided by the
function fmt-doc-example, which takes two arguments: an arbitrary true
list and state.  To see how fmt-doc-example works, :pe fmt-doc-example.

     (fmt-doc-example '(a b c d e f g h i j k l m n o p) state)

will produce the output

        Here is a true list:  (A B C D E F G H I J K L M N O P).  It has 16
        elements, the third of which is C.

        We could print each element in square brackets:
        ([A], [B], [C], [D], [E], [F], [G], [H], [I], [J], [K], [L], [M], [N],
        [almost there: O], [the end: P]).  And if we wished to itemize them
        into column 15 we could do it like this
        0123456789012345
            0 (zeroth) A
            1 (first)  B
            2 (second) C
            3 (third)  D
            4 (fourth) E
            5 (fifth)  F
            6 (sixth)  G
            7 (seventh)
                       H
            8 (eighth) I
            9 (ninth)  J
           10 (tenth)  K
           11 (eleventh)
                       L
           12 (twelfth)
                       M
           13 (thirteenth)
                       N
           14 (14th)   O
           15 (15th)   P
        End of example.

and return (mv 15 state).

Finally, we should remind the reader that fmt and its subfunctions,
most importantly fmt0, are written entirely in ACL2.  We make this
comment for two reasons.  First, it illustrates the fact that quite low
level code can be efficiently written in the language.  Second, it
means that as a last resort for documentation purposes you can read the
source code without changing languages.


File: acl2-doc-emacs.info,  Node: FMT!,  Next: FMT!-TO-STRING,  Prev: FMT,  Up: ACL2-BUILT-INS

FMT!    :(str alist co-channel state evisc) => state

This function is nearly identical to fmt; see *note FMT::.  The only
difference is that fmt may insert backslash (\) characters when forced
to print past the right margin in order to make the output a bit
clearer in that case.  Use fmt! instead if you want to be able to read
the forms back in.


File: acl2-doc-emacs.info,  Node: FMT!-TO-STRING,  Next: FMT-TO-COMMENT-WINDOW,  Prev: FMT!,  Up: ACL2-BUILT-INS

FMT!-TO-STRING    See *note PRINTING-TO-STRINGS::.


File: acl2-doc-emacs.info,  Node: FMT-TO-COMMENT-WINDOW,  Next: FMT-TO-STRING,  Prev: FMT!-TO-STRING,  Up: ACL2-BUILT-INS

FMT-TO-COMMENT-WINDOW    print to the comment window

See *note CW:: for an introduction to the comment window and the usual
way to print it.

Function fmt-to-comment-window is identical to fmt1 (see *note FMT::),
except that the channel is *standard-co* and the ACL2 state is neither
an input nor an output.  An analogous function, fmt-to-comment-window!,
prints with fmt! instead of fmt, in order to avoid insertion of
backslash (\) characters for margins; also see *note CW!::.  Note that
even if you change the value of ld special standard-co (see *note
STANDARD-CO::), fmt-to-comment-window will print to *standard-co*,
which is the original value of standard-co.

     General Form:
     (fmt-to-comment-window fmt-string alist col evisc-tuple)

where these arguments are as desribed for fmt1; see *note FMT::.


File: acl2-doc-emacs.info,  Node: FMT-TO-STRING,  Next: FMT1,  Prev: FMT-TO-COMMENT-WINDOW,  Up: ACL2-BUILT-INS

FMT-TO-STRING    See *note PRINTING-TO-STRINGS::.


File: acl2-doc-emacs.info,  Node: FMT1,  Next: FMT1!,  Prev: FMT-TO-STRING,  Up: ACL2-BUILT-INS

FMT1    :(str alist col co-channel state evisc) => (mv col state)

See *note FMT:: for further explanation, including documentation of the
tilde-directives.


File: acl2-doc-emacs.info,  Node: FMT1!,  Next: FMT1!-TO-STRING,  Prev: FMT1,  Up: ACL2-BUILT-INS

FMT1!    :(str alist col channel state evisc) => (mv col state)

This function is nearly identical to fmt1; see *note FMT1::.  The only
difference is that fmt1 may insert backslash (\) characters when forced
to print past the right margin in order to make the output a bit
clearer in that case.  Use fmt1! instead if you want to be able to read
the forms back in.


File: acl2-doc-emacs.info,  Node: FMT1!-TO-STRING,  Next: FMT1-TO-STRING,  Prev: FMT1!,  Up: ACL2-BUILT-INS

FMT1!-TO-STRING    See *note PRINTING-TO-STRINGS::.


File: acl2-doc-emacs.info,  Node: FMT1-TO-STRING,  Next: FOURTH,  Prev: FMT1!-TO-STRING,  Up: ACL2-BUILT-INS

FMT1-TO-STRING    See *note PRINTING-TO-STRINGS::.


File: acl2-doc-emacs.info,  Node: FOURTH,  Next: GET-OUTPUT-STREAM-STRING$,  Prev: FMT1-TO-STRING,  Up: ACL2-BUILT-INS

FOURTH    fourth member of the list

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: GET-OUTPUT-STREAM-STRING$,  Next: GETENV$,  Prev: FOURTH,  Up: ACL2-BUILT-INS

GET-OUTPUT-STREAM-STRING$    See *note IO::.


File: acl2-doc-emacs.info,  Node: GETENV$,  Next: GETPROP,  Prev: GET-OUTPUT-STREAM-STRING$,  Up: ACL2-BUILT-INS

GETENV$    read an environment variable

(Getenv$ str state), where str is a string, reads the value of
environment variable str, returning a value of nil if none is found or
if the read fails.  The logical story is that getenv$ reads its value
from the oracle field of the ACL2 state.  The return value is thus a
triple of the form (mv erp val state), where erp will always be nil in
practice, and logically, val is the top of the acl2-oracle field of the
state and the returned state has the updated (popped) acl2-oracle.

     Example:
     (getenv$ "PWD" state) ==> (mv nil "/u/joe/work" state)

Also see *note SETENV$::.


File: acl2-doc-emacs.info,  Node: GETPROP,  Next: GOOD-ATOM-LISTP,  Prev: GETENV$,  Up: ACL2-BUILT-INS

GETPROP    access fast property lists

     General form:
     (getprop symb key default world-name world-alist)

See community book books/misc/getprop.lisp for an example that
illustrates the use of ACL2 utilities getprop and putprop to take
advantage of under-the-hood Lisp (hashed) property lists.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: GOOD-ATOM-LISTP,  Next: HARD-ERROR,  Prev: GETPROP,  Up: ACL2-BUILT-INS

GOOD-ATOM-LISTP    recognizer for a true list of "good" atoms

The predicate good-atom-listp tests whether its argument is a
true-listp of "good" atoms, i.e., where each element is a number, a
symbol, a character, or a string.

Also see *note ATOM-LISTP::.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: HARD-ERROR,  Next: IDENTITY,  Prev: GOOD-ATOM-LISTP,  Up: ACL2-BUILT-INS

HARD-ERROR    print an error message and stop execution

(Hard-error ctx str alist) causes evaluation to halt with a short
message using the "context" ctx.  An error message is first printed
using the string str and alist alist that are of the same kind as
expected by fmt.  See *note FMT::.  Also see *note ER:: for a macro
that provides a unified way of signaling errors.

Hard-error has a guard of t.  Also see *note ILLEGAL:: for a similar
capability which however has a guard of nil that supports static
checking using guard verification, rather than using dynamic (run-time)
checking.   This distinction is illustrated elsewhere: see *note
PROG2$:: for examples.

Semantically, hard-error ignores its arguments and always returns nil.
But if a call (hard-error ctx str alist) is encountered during
evaluation, then the string str is printed using the association list
alist (as in fmt), after which evaluation halts immediately.  Here is a
trivial, contrived example.

     ACL2 !>(cons 3 (hard-error 'my-context
                                 "Printing 4: ~n0"
                                 (list (cons #\0 4))))


     HARD ACL2 ERROR in MY-CONTEXT:  Printing 4: four



     ACL2 Error in TOP-LEVEL:  Evaluation aborted.

     ACL2 !>


File: acl2-doc-emacs.info,  Node: IDENTITY,  Next: IF,  Prev: HARD-ERROR,  Up: ACL2-BUILT-INS

IDENTITY    the identity function

(Identity x) equals x; what else can we say?

Identity is a Common Lisp function.  See any Common Lisp documentation
for more information.


File: acl2-doc-emacs.info,  Node: IF,  Next: IFF,  Prev: IDENTITY,  Up: ACL2-BUILT-INS

IF    if-then-else function

(if x y z) is equal to y if x is any value other than nil, and is equal
to z if x is nil.

Only one of y, z is evaluated when (if x y z) is evaluated.

If has a guard of t.

If is part of Common Lisp.  See any Common Lisp documentation for more
information.


File: acl2-doc-emacs.info,  Node: IFF,  Next: IFIX,  Prev: IF,  Up: ACL2-BUILT-INS

IFF    logical "if and only if"

Iff is the ACL2 biconditional, "if and only if".  (iff P Q) means that
either P and Q are both false (i.e., nil) or both true (i.e., not nil).

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: IFIX,  Next: ILLEGAL,  Prev: IFF,  Up: ACL2-BUILT-INS

IFIX    coerce to an integer

Ifix simply returns any integer argument unchanged, returning 0 on a
non-integer argument.  Also see *note NFIX::, see *note RFIX::, see
*note REALFIX:: and see *note FIX:: for analogous functions that coerce
to a natural number, a rational number, a real, and a number,
respectively.

Ifix has a guard of t.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: ILLEGAL,  Next: IMAGPART,  Prev: IFIX,  Up: ACL2-BUILT-INS

ILLEGAL    print an error message and stop execution

(Illegal ctx str alist) causes evaluation to halt with a short message
using the "context" ctx.  An error message is first printed using the
string str and alist alist that are of the same kind as expected by
fmt.  See *note FMT::, and see *note PROG2$:: for an example of how to
use a related function, hard-error (see *note HARD-ERROR::).  Also see
*note ER:: for a macro that provides a unified way of signaling errors.

The difference between illegal and hard-error is that the former has a
guard of nil while the latter has a guard of t.  Thus, you may want to
use illegal rather than hard-error when you intend to do guard
verification at some point, and you expect the guard to guarantee that
the illegal call is never executed.  See *note PROG2$:: for an example.


File: acl2-doc-emacs.info,  Node: IMAGPART,  Next: IMPLIES,  Prev: ILLEGAL,  Up: ACL2-BUILT-INS

IMAGPART    imaginary part of a complex number

Completion Axiom (completion-of-imagpart):

     (equal (imagpart x)
            (if (acl2-numberp x)
                (imagpart x)
              0))

Guard for (imagpart x):

     (acl2-numberp x)


File: acl2-doc-emacs.info,  Node: IMPLIES,  Next: IMPROPER-CONSP,  Prev: IMAGPART,  Up: ACL2-BUILT-INS

IMPLIES    logical implication

Implies is the ACL2 implication function.  (implies P Q) means that
either P is false (i.e., nil) or Q is true (i.e., not nil).

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: IMPROPER-CONSP,  Next: INT=,  Prev: IMPLIES,  Up: ACL2-BUILT-INS

IMPROPER-CONSP    recognizer for improper (non-null-terminated) non-empty lists

Improper-consp is the function that checks whether its argument is a
non-empty list that ends in other than nil.  See *note PROPER-CONSP::
and also see *note TRUE-LISTP::.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: INT=,  Next: INTEGER-LENGTH,  Prev: IMPROPER-CONSP,  Up: ACL2-BUILT-INS

INT=    test equality of two integers

(int= x y) is logically equivalent to (equal x y).

Unlike equal, int= requires its arguments to be numbers (or else causes
a guard violation; see *note GUARD::).  Generally, int= is executed
more efficiently than equal or = on integers.


File: acl2-doc-emacs.info,  Node: INTEGER-LENGTH,  Next: INTEGER-LISTP,  Prev: INT=,  Up: ACL2-BUILT-INS

INTEGER-LENGTH    number of bits in two's complement integer representation

For non-negative integers, (integer-length i) is the minimum number of
bits needed to represent the integer.  Any integer can be represented
as a signed two's complement field with a minimum of (+ (integer-length
i) 1) bits.

The guard for integer-length requires its argument to be an integer.
Integer-length is defined in Common Lisp.  See any Common Lisp
documentation for more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: INTEGER-LISTP,  Next: INTEGERP,  Prev: INTEGER-LENGTH,  Up: ACL2-BUILT-INS

INTEGER-LISTP    recognizer for a true list of integers

The predicate integer-listp tests whether its argument is a true list
of integers.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: INTEGERP,  Next: INTERN,  Prev: INTEGER-LISTP,  Up: ACL2-BUILT-INS

INTEGERP    recognizer for whole numbers

(integerp x) is true if and only if x is an integer.


File: acl2-doc-emacs.info,  Node: INTERN,  Next: INTERN$,  Prev: INTEGERP,  Up: ACL2-BUILT-INS

INTERN    create a new symbol in a given package

(intern symbol-name symbol-package-name) returns a symbol with the
given symbol-name and the given symbol-package-name.  We restrict
Common Lisp's intern so that the second argument is either the symbol
*main-lisp-package-name*, the value of that constant, or is one of
"ACL2", "ACL2-INPUT-CHANNEL", "ACL2-OUTPUT-CHANNEL", or "KEYWORD".  To
avoid that restriction, see *note INTERN$::.

In ACL2 intern is actually implemented as a macro that expands to a
call of a similar function whose second argument is a symbol.  Invoke
:pe intern to see the definition, or see *note
INTERN-IN-PACKAGE-OF-SYMBOL::.

To see why is intern so restricted consider (intern "X" "P").  In
particular, is it a symbol and if so, what is its symbol-package-name?
One is tempted to say "yes, it is a symbol in the package "P"."  But if
package "P" has not yet been defined, that would be premature because
the imports to the package are unknown.  For example, if "P" were
introduced with

     (defpkg "P" '(LISP::X))

then in Common Lisp (symbol-package-name (intern "X" "P")) returns
"LISP".

The obvious restriction on intern is that its second argument be the
name of a package known to ACL2.  We cannot express such a restriction
(except, for example, by limiting it to those packages known at some
fixed time, as we do).  Instead, we provide intern-in-package-of-symbol
which requires a "witness symbol" for the package instead of the
package.  The witness symbol is any symbol (expressible in ACL2) and
uniquely specifies a package necessarily known to ACL2.


File: acl2-doc-emacs.info,  Node: INTERN$,  Next: INTERN-IN-PACKAGE-OF-SYMBOL,  Prev: INTERN,  Up: ACL2-BUILT-INS

INTERN$    create a new symbol in a given package

Intern$ is a macro that behaves the same as the macro intern, except
for weakening the restriction to a fixed set of package names so that
any package name other than "" is legal.  See *note INTERN::.  Note
that if you evaluate a call (intern$ x y) for which there is no package
with name y that is known to ACL2, you will get an error.

(Intern$ x y) expands to:

     (intern-in-package-of-symbol x (pkg-witness y))

See *note INTERN-IN-PACKAGE-OF-SYMBOL:: and see *note PKG-WITNESS::.


File: acl2-doc-emacs.info,  Node: INTERN-IN-PACKAGE-OF-SYMBOL,  Next: INTERSECTION$,  Prev: INTERN$,  Up: ACL2-BUILT-INS

INTERN-IN-PACKAGE-OF-SYMBOL    create a symbol with a given name

Completion Axiom (completion-of-intern-in-package-of-symbol):

     (equal (intern-in-package-of-symbol x y)
            (if (and (stringp x)
                     (symbolp y))
                (intern-in-package-of-symbol x y)
              nil))

Guard for (intern-in-package-of-symbol x y):

     (and (stringp x) (symbolp y))

Intuitively, (intern-in-package-of-symbol x y) creates a symbol with
symbol-name x interned in the package containing y.  More precisely,
suppose x is a string, y is a symbol with symbol-package-name pkg and
that the defpkg event creating pkg had the list of symbols imports as
the value of its second argument.  Then (intern-in-package-of-symbol x
y) returns a symbol, ans, the symbol-name of ans is x, and the
symbol-package-name of ans is pkg, unless x is the symbol-name of some
member of imports with symbol-package-name ipkg, in which case the
symbol-package-name of ans is ipkg.  Because defpkg requires that there
be no duplications among the symbol-names of the imports,
intern-in-package-of-symbol is uniquely defined.

For example, suppose "MY-PKG" was created by

     (defpkg "MY-PKG" '(ACL2::ABC LISP::CAR)).

Let w be 'my-pkg::witness.  Observe that

     (symbolp w) is t                     ; w is a symbol
     (symbol-name w) is "WITNESS"         ; w's name is "WITNESS"
     (symbol-package-name w) is "MY-PKG"  ; w is in the package "MY-PKG"

The construction of w illustrates one way to obtain a symbol in a given
package:  write it down as a constant using the double-colon notation.

But another way to obtain a symbol in a given package is to create it
with intern-in-package-of-symbol.

     (intern-in-package-of-symbol "XYZ" w) is MY-PKG::XYZ

     (intern-in-package-of-symbol "ABC" w) is ACL2::ABC

     (intern-in-package-of-symbol "CAR" w) is LISP::CAR

     (intern-in-package-of-symbol "car" w) is MY-PKG::|car|


File: acl2-doc-emacs.info,  Node: INTERSECTION$,  Next: INTERSECTION-EQ,  Prev: INTERN-IN-PACKAGE-OF-SYMBOL,  Up: ACL2-BUILT-INS

INTERSECTION$    elements of one list that are not elements of another

     General Forms:
     (intersection$ l1 l2 ... lk)
     (intersection$ l1 l2 ... lk :test 'eql) ; same as above
     (intersection$ l1 l2 ... lk :test 'eq)    ; same, but eq is equality test
     (intersection$ l1 l2 ... lk :test 'equal) ; same, but equal is equality test

(Intersection$ x y) equals a list that contains the members of x that
are also members of y.  More precisely, the resulting list is the
result of deleting from x those members that that are not members of y.
The optional keyword, :TEST, has no effect logically, but provides the
test (default eql) used for comparing members of the two lists.

Intersection$ need not take exactly two arguments, though it must take
at least one argument: (intersection$ x) is x,  (intersection$ x y z
... :test test) is (intersection$ x (intersection$ y z ... :test test)
:test test), and if :TEST is not supplied, then (intersection$ x y z
...)  is (intersection$ x (intersection$ y z ...)).  For the discussion
below we restrict ourselves, then, to the cases (intersection$ x y) and
(intersection$ x y :test test).

The guard for a call of intersection$ (in the two cases just above)
depends on the test.  In all cases, both arguments must satisfy
true-listp.  If the test is eql, then one of the arguments must satisfy
eqlable-listp.  If the test is eq, then one of the arguments must
satisfy symbol-listp.

See *note EQUALITY-VARIANTS:: for a discussion of the relation between
intersection$ and its variants:

     (intersection-eq x lst) is equivalent to (intersection$ x lst
     :test 'eq);

     (intersection-equal x lst) is equivalent to (intersection$ x lst
     :test 'equal).


In particular, reasoning about any of these primitives reduces to
reasoning about the function intersection-equal.

Note that intersection-eq can take any positive number of arguments, in
analogy to intersection$; indeed, (intersection-eq ...) expands to
(intersection$ ... :test 'eq).  However, intersection-equal is a
function, not a macro, and takes exactly two arguments.

Intersection$ is similar to the Common Lisp primitive intersection.
However, Common Lisp does not specify the order of elements in the
result of a call of intersection.


File: acl2-doc-emacs.info,  Node: INTERSECTION-EQ,  Next: INTERSECTION-EQUAL,  Prev: INTERSECTION$,  Up: ACL2-BUILT-INS

INTERSECTION-EQ    See *note INTERSECTION$::.


File: acl2-doc-emacs.info,  Node: INTERSECTION-EQUAL,  Next: INTERSECTP,  Prev: INTERSECTION-EQ,  Up: ACL2-BUILT-INS

INTERSECTION-EQUAL    See *note INTERSECTION$::.


File: acl2-doc-emacs.info,  Node: INTERSECTP,  Next: INTERSECTP-EQ,  Prev: INTERSECTION-EQUAL,  Up: ACL2-BUILT-INS

INTERSECTP    test whether two lists intersect

     General Forms:
     (set-difference$ l1 l2)
     (set-difference$ l1 l2 :test 'eql)   ; same as above (eql as equality test)
     (set-difference$ l1 l2 :test 'eq)    ; same, but eq is equality test
     (set-difference$ l1 l2 :test 'equal) ; same, but equal is equality test

(Intersectp l1 l2) returns t if l1 and l2 have a member in common, else
it returns nil.  The optional keyword, :TEST, has no effect logically,
but provides the test (default eql) used for comparing members of the
two lists.

The guard for a call of intersectp depends on the test.  In all cases,
both arguments must satisfy true-listp.  If the test is eql, then one
of the arguments must satisfy eqlable-listp.  If the test is eq, then
one of the arguments must satisfy symbol-listp.

See *note EQUALITY-VARIANTS:: for a discussion of the relation between
intersectp and its variants:

     (intersectp-eq x lst) is equivalent to (intersectp x lst :test
     'eq);

     (intersectp-equal x lst) is equivalent to (intersectp x lst :test
     'equal).


In particular, reasoning about any of these primitives reduces to
reasoning about the function intersectp-equal.


File: acl2-doc-emacs.info,  Node: INTERSECTP-EQ,  Next: INTERSECTP-EQUAL,  Prev: INTERSECTP,  Up: ACL2-BUILT-INS

INTERSECTP-EQ    See *note INTERSECTP::.


File: acl2-doc-emacs.info,  Node: INTERSECTP-EQUAL,  Next: KEYWORD-VALUE-LISTP,  Prev: INTERSECTP-EQ,  Up: ACL2-BUILT-INS

INTERSECTP-EQUAL    See *note INTERSECTP::.


File: acl2-doc-emacs.info,  Node: KEYWORD-VALUE-LISTP,  Next: KEYWORDP,  Prev: INTERSECTP-EQUAL,  Up: ACL2-BUILT-INS

KEYWORD-VALUE-LISTP    recognizer for true lists whose even-position elements are keywords

(keyword-value-listp l) is true if and only if l is a list of even
length of the form (k1 a1 k2 a2 ... kn an), where each ki is a keyword.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: KEYWORDP,  Next: KWOTE,  Prev: KEYWORD-VALUE-LISTP,  Up: ACL2-BUILT-INS

KEYWORDP    recognizer for keywords

(Keywordp x) is true if and only if x is a keyword, i.e., a symbol in
the "KEYWORD" package.  Such symbols are typically printed using a colon
(:) followed by the symbol-name of the symbol.

Keywordp has a guard of t.

Keywordp is a Common Lisp function.  See any Common Lisp documentation
for more information.  The following log may be illuminating.

     ACL2 !>(intern "ABC" "KEYWORD")
     :ABC
     ACL2 !>(symbol-name ':ABC)
     "ABC"
     ACL2 !>(symbol-package-name ':ABC)
     "KEYWORD"
     ACL2 !>

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: KWOTE,  Next: KWOTE-LST,  Prev: KEYWORDP,  Up: ACL2-BUILT-INS

KWOTE    quote an arbitrary object

For any object x, (kwote x) returns the two-element list whose elements
are the symbol quote and the given x, respectively.  The guard of
(kwote x) is t.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: KWOTE-LST,  Next: LAST,  Prev: KWOTE,  Up: ACL2-BUILT-INS

KWOTE-LST    quote an arbitrary true list of objects

The function kwote-lst applies the function kwote to each element of a
given list.  The guard of (kwote-lst lst) is (true-listp lst).

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: LAST,  Next: LEN,  Prev: KWOTE-LST,  Up: ACL2-BUILT-INS

LAST    the last cons (not element) of a list

(Last l) is the last cons of a list.  Here are examples.

     ACL2 !>(last '(a b . c))
     (B . C)
     ACL2 !>(last '(a b c))
     (C)

(Last l) has a guard of (listp l); thus, l need not be a true-listp.

Last is a Common Lisp function.  See any Common Lisp documentation for
more information.  Unlike Common Lisp, we do not allow an optional
second argument for last.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: LEN,  Next: LENGTH,  Prev: LAST,  Up: ACL2-BUILT-INS

LEN    length of a list

Len returns the length of a list.

A Common Lisp function that is appropriate for both strings and proper
lists is length; see *note LENGTH::.  The guard for len is t.

(Low-level implementation note.  ACL2 provides a highly-optimized
implementation of len, which is tail-recursive and fixnum-aware, that
differs from its simple ACL2 definition.)

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: LENGTH,  Next: LET,  Prev: LEN,  Up: ACL2-BUILT-INS

LENGTH    length of a string or proper list

Length is the function for determining the length of a sequence.  In
ACL2, the argument is required to be either a true-listp or a string.

Length is a Common Lisp function.  See any Common Lisp documentation
for more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: LET,  Next: LET*,  Prev: LENGTH,  Up: ACL2-BUILT-INS

LET    binding of lexically scoped (local) variables

     Example LET Form:
     (let ((x (* x x))
           (y (* 2 x)))
      (list x y))

If the form above is executed in an environment in which x has the
value -2, then the result is '(4 -4).

Let expressions bind variables so that their "local" values, the values
they have when the "body" of the let is evaluated, are possibly
different than their "global" values, the values they have in the
context in which the let expression appears.  In the let expression
above, the local variables bound by the let are x and y.  They are
locally bound to the values delivered by the two forms (* x x) and (* 2
x), respectively, that appear in the "bindings" of the let.  The body
of the let is (list x y).

Suppose that the let expression above occurs in a context in which x
has the value -2.  (The global value of y is irrelevant to this
example.)  For example, one might imagine that the let form above
occurs as the body of some function, fn, with the formal parameter x
and we are evaluating (fn -2).

To evaluate the let above in a context in which x is -2, we first
evaluate the two forms specifying the local values of the variables.
Thus, (* x x) is evaluated and produces 4 (because x is -2) and (* 2 x)
is evaluated and produces -4 (because x is -2).  Then x and y are bound
to these values and the body of the let is evaluated.  Thus, when the
body, (list x y) is evaluated, x is 4 and y is -4.  Thus, the body
produces '(4 -4).

Note that the binding of y, which is written after the binding of x and
which mentions x, nevertheless uses the global value of x, not the new
local value.  That is, the local variables of the let are bound "in
parallel" rather than "sequentially." In contrast, if the

     Example LET* Form:
     (let* ((x (* x x))
            (y (* 2 x)))
      (list x y))

is evaluated when the global value of x is -2, then the result is '(4
8), because the local value of y is computed after x has been bound to
4.  Let* binds its local variables "sequentially."

     General LET Forms:
     (let ((var1 term1) ... (varn termn)) body)
     and
     (let ((var1 term1) ... (varn termn))
      (declare ...) ... (declare ...)
      body)

where the vari are distinct variables, the termi are terms involving
only variables bound in the environment containing the let, and body is
a term involving only the vari plus the variables bound in the
environment containing the let.  Each vari must be used in body or else
declared ignored.

A let form is evaluated by first evaluating each of the termi,
obtaining for each a vali.  Then, each vari is bound to the
corresponding vali and body is evaluated.

Actually, let forms are just abbreviations for certain uses of lambda
notation.  In particular

     (let ((var1 term1) ... (varn termn)) (declare ...) body)

is equivalent to

     ((lambda (var1 ... varn)
        (declare ...)
        body)
      term1 ... termn).

Let* forms are used when it is desired to bind the vari sequentially,
i.e., when the local values of preceding varj are to be used in the
computation of the local value for vari.

     General LET* Forms:
     (let* ((var1 term1) ... (varn termn)) body)
     and
     (let* ((var1 term1) ... (varn termn))
      (declare (ignore x1 ... xm))
      body)

where the vari are variables (not necessarily distinct), the termi are
terms involving only variables bound in the environment containing the
let* and those varj such that j<i, and body is a term involving only
the vari plus the variables bound in the environment containing the
let*.  Each vari must be used either in some subsequent termj or in
body, except that in the second form above we make an exception when
vari is among the xk, in which case vari must not be thus used.  Note
that let* does not permit the inclusion of any declare forms other than
one as shown above.  In the second general form above, every xk must be
among the vari, and furthermore, xk may not equal vari and varj for
distinct i, j.

The first let* above is equivalent to

     (let ((var1 term1))
      ...
      (let ((varn termn)) body)...)

Thus, the termi are evaluated successively and after each evaluation
the corresponding vali is bound to the value of termi.  The second let*
is similarly expanded, except that each for each vari that is among the
(x1 ... xm), the form (declare (ignore vari)) is inserted immediately
after (vari termi).

Each (vari termi) pair in a let or let* form is called a "binding" of
vari and the vari are called the "local variables" of the let or let*.
The common use of let and let* is to save the values of certain
expressions (the termi) so that they may be referenced several times in
the body without suggesting their recomputation.

Let is part of Common Lisp.  See any Common Lisp documentation for more
information.


File: acl2-doc-emacs.info,  Node: LET*,  Next: LEXORDER,  Prev: LET,  Up: ACL2-BUILT-INS

LET*    binding of lexically scoped (local) variables

     Example LET* Forms:
     (let* ((x (* x x))
            (y (* 2 x)))
      (list x y))

     (let* ((x (* x x))
            (y (* 2 x))
            (x (* x y))
            (a (* x x)))
      (declare (ignore a))
      (list x y))

If the forms above are executed in an environment in which x has the
value -2, then the respective results are '(4 8) and '(32 8).  See
*note LET:: for a discussion of both let and let*, or read on for a
briefer discussion.

The difference between let and let* is that the former binds its local
variables in parallel while the latter binds them sequentially.  Thus,
in let*, the term evaluated to produce the local value of one of the
locally bound variables is permitted to reference any locally bound
variable occurring earlier in the binding list and the value so
obtained is the newly computed local value of that variable.  See *note
LET::.

In ACL2 the only declare forms allowed for a let* form are ignore,
ignorable, and type.  See *note DECLARE::.  Moreover, no variable
declared ignored or ignorable may be bound more than once.  A variable
with a type declaration may be bound more than once, in which case the
type declaration is treated by ACL2 as applying to each binding
occurrence of that variable.  It seems unclear from the Common Lisp spec
whether the underlying Lisp implementation is expected to apply such a
declaration to more than one binding occurrence, however, so
performance in such cases may depend on the underlying Lisp.

Let* is a Common Lisp macro.  See any Common Lisp documentation for
more information.


File: acl2-doc-emacs.info,  Node: LEXORDER,  Next: LIST,  Prev: LET*,  Up: ACL2-BUILT-INS

LEXORDER    total order on ACL2 objects

Lexorder is a non-strict total order, a "less than or equal," on ACL2
objects.  Also see *note ALPHORDER::, the restriction of lexorder to
atoms; the notion of "non-strict total order" is defined there.

Lexorder has a guard of t.

For lexorder, an atom and a cons are ordered so that the atom comes
first, and two conses are ordered so that the one with the recursively
smaller car comes first, with the cdrs being compared only if the cars
are equal.   Lexorder compares two atoms by using alphorder.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: LIST,  Next: LIST*,  Prev: LEXORDER,  Up: ACL2-BUILT-INS

LIST    build a list

List is the macro for building a list of objects.  For example, (list 5
6 7) returns a list of length 3 whose elements are 5, 6, and 7
respectively.  Also see *note LIST*::.

List is defined in Common Lisp.  See any Common Lisp documentation for
more information.


File: acl2-doc-emacs.info,  Node: LIST*,  Next: LISTP,  Prev: LIST,  Up: ACL2-BUILT-INS

LIST*    build a list

List* is the Common Lisp macro for building a list of objects from
given elements and a tail.  For example, (list* 5 6 '(7 8 9)) equals
the list '(5 6 7 8 9).  Also see *note LIST::.

List* is a Common Lisp function.  See any Common Lisp documentation for
more information.


File: acl2-doc-emacs.info,  Node: LISTP,  Next: LOGAND,  Prev: LIST*,  Up: ACL2-BUILT-INS

LISTP    recognizer for (not necessarily proper) lists

(listp x) is true when x is either a cons pair or is nil.

Listp has no guard, i.e., its guard is t.

Listp is a Common Lisp function.  See any Common Lisp documentation for
more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: LOGAND,  Next: LOGANDC1,  Prev: LISTP,  Up: ACL2-BUILT-INS

LOGAND    bitwise logical `and' of zero or more integers

When integers are viewed in their two's complement representation,
logand returns their bitwise logical `and'.  In ACL2 logand is a macro
that expands into calls of the binary function binary-logand, except
that (logand) expands to -1 and (logand x) expands to x.

The guard for binary-logand requires its arguments to be integers.
Logand is defined in Common Lisp.  See any Common Lisp documentation
for more information.


File: acl2-doc-emacs.info,  Node: LOGANDC1,  Next: LOGANDC2,  Prev: LOGAND,  Up: ACL2-BUILT-INS

LOGANDC1    bitwise logical `and' of two ints, complementing the first

When integers are viewed in their two's complement representation,
logandc1 returns the bitwise logical `and' of the second with the
bitwise logical `not' of the first.

The guard for logandc1 requires its arguments to be integers.  Logandc1
is defined in Common Lisp.  See any Common Lisp documentation for more
information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: LOGANDC2,  Next: LOGBITP,  Prev: LOGANDC1,  Up: ACL2-BUILT-INS

LOGANDC2    bitwise logical `and' of two ints, complementing the second

When integers are viewed in their two's complement representation,
logandc2 returns the bitwise logical `and' of the first with the
bitwise logical `not' of the second.

The guard for logandc2 requires its arguments to be integers.  Logandc2
is defined in Common Lisp.  See any Common Lisp documentation for more
information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: LOGBITP,  Next: LOGCOUNT,  Prev: LOGANDC2,  Up: ACL2-BUILT-INS

LOGBITP    the ith bit of an integer

For a nonnegative integer i and an integer j, (logbitp i j) is a
Boolean, which is t if and only if the value of the ith bit is 1 in the
two's complement representation of j.

(Logbitp i j) has a guard that i is a nonnegative integer and j is an
integer.

Logbitp is a Common Lisp function.  See any Common Lisp documentation
for more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: LOGCOUNT,  Next: LOGEQV,  Prev: LOGBITP,  Up: ACL2-BUILT-INS

LOGCOUNT    number of "on" bits in a two's complement number

(Logcount x) is the number of "on" bits in the two's complement
representation of x.

(Logcount x) has a guard of (integerp x).

Logcount is a Common Lisp function.  See any Common Lisp documentation
for more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: LOGEQV,  Next: LOGIOR,  Prev: LOGCOUNT,  Up: ACL2-BUILT-INS

LOGEQV    bitwise logical equivalence of zero or more integers

When integers are viewed in their two's complement representation,
logeqv returns their bitwise logical equivalence.  In ACL2 logeqv is a
macro that expands into calls of the binary function binary-logeqv,
except that (logeqv) expands to -1 and (logeqv x) expands to x.

The guard for binary-logeqv requires its arguments to be integers.
Logeqv is defined in Common Lisp.  See any Common Lisp documentation
for more information.


File: acl2-doc-emacs.info,  Node: LOGIOR,  Next: LOGNAND,  Prev: LOGEQV,  Up: ACL2-BUILT-INS

LOGIOR    bitwise logical inclusive or of zero or more integers

When integers are viewed in their two's complement representation,
logior returns their bitwise logical inclusive or.  In ACL2 logior is a
macro that expands into calls of the binary function binary-logior,
except that (logior) expands to 0 and (logior x) expands to x.

The guard for binary-logior requires its arguments to be integers.
Logior is defined in Common Lisp.  See any Common Lisp documentation
for more information.


File: acl2-doc-emacs.info,  Node: LOGNAND,  Next: LOGNOR,  Prev: LOGIOR,  Up: ACL2-BUILT-INS

LOGNAND    bitwise logical `nand' of two integers

When integers are viewed in their two's complement representation,
lognand returns their bitwise logical `nand'.

The guard for lognand requires its arguments to be integers.  Lognand
is defined in Common Lisp.  See any Common Lisp documentation for more
information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: LOGNOR,  Next: LOGNOT,  Prev: LOGNAND,  Up: ACL2-BUILT-INS

LOGNOR    bitwise logical `nor' of two integers

When integers are viewed in their two's complement representation,
lognor returns the bitwise logical `nor' of the first with the second.

The guard for lognor requires its arguments to be integers.  Lognor is
defined in Common Lisp.  See any Common Lisp documentation for more
information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: LOGNOT,  Next: LOGORC1,  Prev: LOGNOR,  Up: ACL2-BUILT-INS

LOGNOT    bitwise not of a two's complement number

(lognot i) is the two's complement bitwise `not' of the integer i.

Lognot is actually defined by coercing its argument to an integer (see
*note IFIX::), negating the result, and then subtracting 1.

The guard for lognot requires its argument to be an integer.

Lognot is a Common Lisp function.  See any Common Lisp documentation
for more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: LOGORC1,  Next: LOGORC2,  Prev: LOGNOT,  Up: ACL2-BUILT-INS

LOGORC1    bitwise logical inclusive or of two ints, complementing the first

When integers are viewed in their two's complement representation,
logorc1 returns the bitwise logical inclusive or of the second with the
bitwise logical `not' of the first.

The guard for logorc1 requires its arguments to be integers.  Logorc1
is defined in Common Lisp.  See any Common Lisp documentation for more
information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: LOGORC2,  Next: LOGTEST,  Prev: LOGORC1,  Up: ACL2-BUILT-INS

LOGORC2    bitwise logical inclusive or of two ints, complementing the second

When integers are viewed in their two's complement representation,
logorc2 returns the bitwise logical inclusive or of the first with the
bitwise logical `not' of the second.

The guard for logorc2 requires its arguments to be integers.  Logorc2
is defined in Common Lisp.  See any Common Lisp documentation for more
information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: LOGTEST,  Next: LOGXOR,  Prev: LOGORC2,  Up: ACL2-BUILT-INS

LOGTEST    test if two integers share a `1' bit

When integers x and y are viewed in their two's complement
representation, (logtest x y) is true if and only if there is some
position for which both x and y have a `1' bit in that position.

The guard for logtest requires its arguments to be integers.  Logtest
is defined in Common Lisp.  See any Common Lisp documentation for more
information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: LOGXOR,  Next: LOWER-CASE-P,  Prev: LOGTEST,  Up: ACL2-BUILT-INS

LOGXOR    bitwise logical exclusive or of zero or more integers

When integers are viewed in their two's complement representation,
logxor returns their bitwise logical exclusive or.  In ACL2 logxor is a
macro that expands into calls of the binary function binary-logxor,
except that (logxor) expands to 0 and (logxor x) expands to x.

The guard for binary-logxor requires its arguments to be integers.
Logxor is defined in Common Lisp.  See any Common Lisp documentation
for more information.


File: acl2-doc-emacs.info,  Node: LOWER-CASE-P,  Next: MAKE-CHARACTER-LIST,  Prev: LOGXOR,  Up: ACL2-BUILT-INS

LOWER-CASE-P    recognizer for lower case characters

(Lower-case-p x) is true if and only if x is a lower case character,
i.e., a member of the list #\A, #\B, ..., #\Z.

The guard for lower-case-p requires its argument to be a standard
character (see *note STANDARD-CHAR-P::).

Lower-case-p is a Common Lisp function.  See any Common Lisp
documentation for more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: MAKE-CHARACTER-LIST,  Next: MAKE-LIST,  Prev: LOWER-CASE-P,  Up: ACL2-BUILT-INS

MAKE-CHARACTER-LIST    coerce to a list of characters

Non-characters in the given list are coerced to the character with code
0.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: MAKE-LIST,  Next: MAKE-ORD,  Prev: MAKE-CHARACTER-LIST,  Up: ACL2-BUILT-INS

MAKE-LIST    make a list of a given size

For a nonnegative integer size, (Make-list size) is a list of elements
of length size, each of which is initialized to the :initial-element
(which defaults to nil).

Make-list is a macro in ACL2, defined in terms of a tail recursive
function make-list-ac whose guard requires size to be a nonnegative
integer.  Make-list is a Common Lisp function.  See any Common Lisp
documentation for more information.


File: acl2-doc-emacs.info,  Node: MAKE-ORD,  Next: MAX,  Prev: MAKE-LIST,  Up: ACL2-BUILT-INS

MAKE-ORD    a constructor for ordinals.

Make-ord is the ordinal constructor.  Its use is recommended instead of
using cons to make ordinals.  For a discussion of ordinals, see *note
ORDINALS::.

For any ordinal, alpha < epsilon-0, there exist natural numbers p and
n, positive integers x1, x2, ..., xn and ordinals a1 > a2 > ... > an >
0 such that alpha > a1 and alpha = w^(a1)x1 + w^(a2)x2 + ... + w^(an)xn
+ p.  We call a1 the "first exponent", x1 the "first coefficient", and
the remainder (w^(a2)x2 + ... + w^(an)xn + p) the "rest" of alpha.

(Make-ord fe fco rst) corresponds to the ordinal (w^fe)fco + rst.  Thus
the first infinite ordinal, w (omega), is constructed by

     (make-ord 1 1 0)

and, for example, the ordinal (w^2)5 + w2 + 7 is constructed by:

     (make-ord 2 5 (make-ord 1 2 7)) .

The reason make-ord is used rather than cons is that it allows us to
reason more abstractly about the ordinals, without having to worry
about the underlying representation.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: MAX,  Next: MBE,  Prev: MAKE-ORD,  Up: ACL2-BUILT-INS

MAX    the larger of two numbers

(Max x y) is the larger of the numbers x and y.

The guard for max requires its arguments to be rational (real, in
ACL2(r)) numbers.

Max is a Common Lisp function.  See any Common Lisp documentation for
more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: MBE,  Next: MBE1,  Prev: MAX,  Up: ACL2-BUILT-INS

MBE    attach code for execution

The macro mbe ("must be equal") can be used in function definitions in
order to cause evaluation to use alternate code to that provided for the
logic.  An example is given below.  However, the use of mbe can lead to
non-terminating computations.  See *note DEFEXEC::, perhaps after
reading the present documentation, for a way to prove termination.

In the ACL2 logic, (mbe :exec exec-code :logic logic-code) equals
logic-code; the value of exec-code is ignored.  However, in raw Lisp it
is the other way around: this form macroexpands simply to exec-code.
ACL2's guard verification mechanism ensures that the raw Lisp code is
only evaluated when appropriate, since the guard proof obligations
generated for (the macroexpansion of) this call of mbe include not only
the guard proof obligations from exec-code, but also, under suitable
contextual assumptions, the term (equal exec-code logic-code).  See
*note VERIFY-GUARDS:: (in particular, for discussion of the contextual
assumptions from the :guard and IF-tests) and, for general discussion
of guards, see *note GUARD::.

Normally, during evaluation of an mbe call, only the :logic code is
evaluated unless the call is in the body of a guard-verified function,
in which case only the :exec code is evaluated.  This implies that
equality of :exec and :logic code is never checked at runtime.
(Rather, such equality is proved when verifying guards.)  We started
with "normally" above because there is an exception: during a "safe
mode", which is used in macroexpansion and evaluation of defconst
forms, the :logic and :exec code are both evaluated and their equality
is checked.

Note that the :exec and the :logic code in an mbe call must have the
same return type.  For example, one cannot return (mv * *) while the
other returns just a single value.

Also see *note MBT::, which stands for "must be true."  You may find it
more natural to use mbt for certain applications, as described in its
documentation.

* Menu:


Related topics other than immediate subtopics:
* DEFEXEC:: attach a terminating executable function to a definition

Here is an example of the use of mbe.  Suppose that you want to define
factorial in the usual recursive manner, as follows.

     (defun fact (n)
       (if (zp n)
           1
         (* n (fact (1- n)))))

But perhaps you want to be able to execute calls of fact on large
arguments that cause stack overflows, perhaps during proofs.  (This
isn't a particularly realistic example, but it should serve.)  So,
instead you can define this tail-recursive version of factorial:

     (defun fact1 (n acc)
       (declare (xargs :guard (and (integerp n) (>= n 0) (integerp acc))))
       (if (zp n)
           acc
         (fact1 (1- n) (* n acc))))

We are now ready to define fact using mbe.  Our intention is that
logically, fact is as shown in the first definition above, but that
fact should be executed by calling fact1.  Notice that we defer guard
verification, since we are not ready to prove the correspondence
between fact1 and fact.

     (defun fact (n)
       (declare (xargs :guard (and (integerp n) (>= n 0))
                       :verify-guards nil))
       (mbe :exec  (fact1 n 1)
            :logic (if (zp n)
                       1
                     (* n (fact (1- n))))))

Next, we prove the necessary correspondence lemmas.  Notice the
inclusion of a community book to help with the arithmetic reasoning.

     (include-book "books/arithmetic/top-with-meta")

     (defthm fact1-fact
       (implies (integerp acc)
                (equal (fact1 n acc)
                       (* acc (fact n)))))

We may now do guard verification for fact, which will allow the
execution of the raw Lisp fact function, where the above mbe call
expands simply to (fact1 n 1).

     (verify-guards fact)

Now that guards have been verified, a trace of function calls
illustrates that the evaluation of calls of fact is passed to
evaluation of calls of fact1.  The outermost call below is of the
logical function stored for the definition of fact; all the others are
of actual raw Common Lisp functions.

     ACL2 !>(trace$ fact fact1)
     NIL
     ACL2 !>(fact 3)
     1> (ACL2_*1*_ACL2::FACT 3)
       2> (FACT 3)
         3> (FACT1 3 1)
           4> (FACT1 2 3)
             5> (FACT1 1 6)
               6> (FACT1 0 6)
               <6 (FACT1 6)
             <5 (FACT1 6)
           <4 (FACT1 6)
         <3 (FACT1 6)
       <2 (FACT 6)
     <1 (ACL2_*1*_ACL2::FACT 6)
     6
     ACL2 !>

You may occasionally get warnings when you compile functions defined
using mbe.  (For commands that invoke the compiler, see *note
COMPILATION::.)  These can be inhibited by using an ignorable declare
form.  Here is a simple but illustrative example.  Note that the
declarations can optionally be separated into two declare forms.

     (defun foo (x y)
       (declare (ignorable x)
                (xargs :guard (equal x y)))
       (mbe :logic x :exec y))

Finally, we observe that when the body of a function contains a term of
the form (mbe :exec exec-code :logic logic-code), the user is very
unlikely to see any logical difference than if this were replaced by
logic-code.  ACL2 takes various steps to ensure this.  For example, the
proof obligations generated for admitting a function treat the above
mbe term simply as logic-code.  Function expansion, :use hints,
:definition rules, generation of constraints for functional
instantiation, and creation of rules of class :rewrite and
:forward-chaining also treat mbe calls as their :logic code.


File: acl2-doc-emacs.info,  Node: MBE1,  Next: MBT,  Prev: MBE,  Up: ACL2-BUILT-INS

MBE1    attach code for execution

The form (mbe1 exec logic) is equivalent to the forms (mbe :logic logic
:exec exec) and (must-be-equal logic exec).  See *note MBE::.


File: acl2-doc-emacs.info,  Node: MBT,  Next: MEMBER,  Prev: MBE1,  Up: ACL2-BUILT-INS

MBT    introduce a test not to be evaluated

The macro mbt ("must be true") can be used in order to add code in
order to admit function definitions in :logic mode, without paying a
cost in execution efficiency.  Examples below illustrate its intended
use.

Semantically, (mbt x) equals x.  However, in raw Lisp (mbt x) ignores x
entirely, and macroexpands to t.  ACL2's guard verification mechanism
ensures that the raw Lisp code is only evaluated when appropriate,
since a guard proof obligation (equal x t) is generated.  See *note
VERIFY-GUARDS:: and, for general discussion of guards, see *note
GUARD::.

Also see *note MBE::, which stands for "must be equal."  Although mbt
is more natural in many cases, mbe has more general applicability.  In
fact, (mbt x) is essentially defined to be (mbe :logic x :exec t).

We can illustrate the use of mbt on the following generic example, where
<g>, <test>, <rec-x>, and <base> are intended to be terms involving
only the variable x.

     (defun foo (x)
       (declare (xargs :guard <g>))
       (if <test>
           (foo <rec-x>)
         <base>))

In order to admit this function, ACL2 needs to discharge the proof
obligation that <rec-x> is smaller than x, namely:

     (implies <test>
              (o< (acl2-count <rec-x>)
                   (acl2-count x)))

But suppose we need to know that <g> is true in order to prove this.
Since <g> is only the guard, it is not part of the logical definition
of foo.  A solution is to add the guard to the definition of foo, as
follows.

     (defun foo (x)
       (declare (xargs :guard <g>))
       (if (mbt <g>)
           (if <test>
               (foo <rec-x>)
             <base>)
         nil))

If we do this using <g> rather than (mbt <g>), then evaluation of every
recursive call of foo will cause the evaluation of (the appropriate
instance of) <g>.  But since (mbt <g>) expands to t in raw Lisp, then
once we verify the guards of foo, the evaluations of <g> will be
avoided (except at the top level, when we check the guard before
allowing evaluation to take place in Common Lisp).

Other times, the guard isn't the issue, but rather, the problem is that
a recursive call has an argument that itself is a recursive call.  For
example, suppose that <rec-x> is of the form (foo <expr>).  There is no
way we can hope to discharge the termination proof obligation shown
above.  A standard solution is to add some version of this test:

     (mbt (o< (acl2-count <rec-x>) (acl2-count x)))

Here is a specific example based on one sent by Vernon Austel.

     (defun recurX2 (n)
       (declare (xargs :guard (and (integerp n) (<= 0 n))
                       :verify-guards nil))
       (cond ((zp n) 0)
             (t (let ((call (recurX2 (1- n))))
                  (if (mbt (< (acl2-count call) n))
                      (recurX2 call)
                    1 ;; this branch is never actually taken
                    )))))

     (defthm recurX2-0
      (equal (recurX2 n) 0))

     (verify-guards recurX2)

If you (trace$ acl2-count), you will see that evaluation of (recurX2 2)
causes several calls of acl2-count before the verify-guards.  But this
evaluation does not call acl2-count after the verify-guards, because
the ACL2 evaluation mechanism uses raw Lisp to do the evaluation, and
the form (mbt (< (acl2-count call) n)) macroexpands to t in Common Lisp.

You may occasionally get warnings when you compile functions defined
using mbt.  (For commands that invoke the compiler, see *note
COMPILATION::.)  These can be inhibited by using an ignorable declare
form.  Here is a simple but illustrative example.  Note that the
declarations can optionally be separated into two declare forms.

     (defun foo (x y)
       (declare (ignorable x)
                (xargs :guard (equal x t)))
       (and (mbt x) y))


File: acl2-doc-emacs.info,  Node: MEMBER,  Next: MEMBER-EQ,  Prev: MBT,  Up: ACL2-BUILT-INS

MEMBER    membership predicate

     General Forms:
     (member x lst)
     (member x lst :test 'eql)   ; same as above (eql as equality test)
     (member x lst :test 'eq)    ; same, but eq is equality test
     (member x lst :test 'equal) ; same, but equal is equality test

(Member x lst) equals the longest tail of the list lst that begins with
x, or else nil if no such tail exists.  The optional keyword, :TEST,
has no effect logically, but provides the test (default eql) used for
comparing x with successive elements of lst.

The guard for a call of member depends on the test.  In all cases, the
second argument must satisfy true-listp.  If the test is eql, then
either the first argument must be suitable for eql (see *note
EQLABLEP::) or the second argument must satisfy eqlable-listp.  If the
test is eq, then either the first argument must be a symbol or the
second argument must satisfy symbol-listp.

See *note EQUALITY-VARIANTS:: for a discussion of the relation between
member and its variants:

     (member-eq x lst) is equivalent to (member x lst :test 'eq);

     (member-equal x lst) is equivalent to (member x lst :test 'equal).


In particular, reasoning about any of these primitives reduces to
reasoning about the function member-equal.

Member is defined by Common Lisp.  See any Common Lisp documentation for
more information.


File: acl2-doc-emacs.info,  Node: MEMBER-EQ,  Next: MEMBER-EQUAL,  Prev: MEMBER,  Up: ACL2-BUILT-INS

MEMBER-EQ    See *note MEMBER::.


File: acl2-doc-emacs.info,  Node: MEMBER-EQUAL,  Next: MIN,  Prev: MEMBER-EQ,  Up: ACL2-BUILT-INS

MEMBER-EQUAL    See *note MEMBER::.


File: acl2-doc-emacs.info,  Node: MIN,  Next: MINUSP,  Prev: MEMBER-EQUAL,  Up: ACL2-BUILT-INS

MIN    the smaller of two numbers

(Min x y) is the smaller of the numbers x and y.

The guard for min requires its arguments to be rational (real, in
ACL2(r)) numbers.

Min is a Common Lisp function.  See any Common Lisp documentation for
more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: MINUSP,  Next: MOD,  Prev: MIN,  Up: ACL2-BUILT-INS

MINUSP    test whether a number is negative

(Minusp x) is true if and only if x < 0.

The guard of minusp requires its argument to be a rational (real, in
ACL2(r)) number.

Minusp is a Common Lisp function.  See any Common Lisp documentation
for more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: MOD,  Next: MOD-EXPT,  Prev: MINUSP,  Up: ACL2-BUILT-INS

MOD    remainder using floor

     ACL2 !>(mod 14 3)
     2
     ACL2 !>(mod -14 3)
     1
     ACL2 !>(mod 14 -3)
     -1
     ACL2 !>(mod -14 -3)
     -2
     ACL2 !>(mod -15 -3)
     0
     ACL2 !>

(Mod i j) is that number k that (* j (floor i j)) added to k equals i.

The guard for (mod i j) requires that i and j are rational (real, in
ACL2(r)) numbers and j is non-zero.

Mod is a Common Lisp function.  See any Common Lisp documentation for
more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: MOD-EXPT,  Next: MSG,  Prev: MOD,  Up: ACL2-BUILT-INS

MOD-EXPT    exponential function

(mod-expt r i m) is the result of raising the number r to the integer
power i and then taking the residue mod m.  That is, (mod-expt r i m)
is equal to (mod (expt r i) m).

The guard for (mod-expt r i m) is that r is a rational number and i is
an integer; if r is 0 then i is nonnegative; and m is a non-zero
rational number.

In some implementations (GCL Version 2.7.0 as of this writing), this
function is highly optimized when r and i are natural numbers, not both
zero, and m is a positive integer.  For other Lisp implementations,
consider using function mod-expt-fast, defined in the community book
arithmetic-3/floor-mod/mod-expt-fast.lisp, which should still provide
significantly improved performance over this function.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: MSG,  Next: MUST-BE-EQUAL,  Prev: MOD-EXPT,  Up: ACL2-BUILT-INS

MSG    construct a "message" suitable for the ~@ directive of fmt

See *note FMT:: for background on formatted printing with ACL2.

We document msg precisely below, but first, we give an informal
introduction and illustrate with an example.  Suppose you are writing a
program that is to do some printing.  Typically, you will either pass
the ACL2 state around (see *note PROGRAMMING-WITH-STATE::) and use
formatted printing functions that take the state as an argument (see
*note FMT::)), or else you might avoid using state by calling the
utility, cw, to do you printing.  Alternatively, you might print error
messages upon encountering illegal situations; see *note ER::.  But
there are times where instead of printing immediately, you may prefer
to pass messages around, for example to accumulate them before printing
a final message.  In such cases, it may be desirable to construct
"message" objects to pass around.

For example, consider the following pair of little programs.  The first
either performs a computation or prints an error, and the second calls
the first on two inputs.


     (defun invert1 (x)
       (if (consp x)
           (cons (cdr x) (car x))
         (prog2$ (cw "ERROR: ~x0 expected a cons, but was given ~x1.~|"
                     'invert1 x)
                 nil)))

     (defun invert2 (x1 x2)
       (list (invert1 x1) (invert1 x2)))

For example:


       ACL2 !>(invert1 '(3 . 4))
       (4 . 3)
       ACL2 !>(invert1 'a)
       ERROR: INVERT1 expected a cons, but was given A.
       NIL
       ACL2 !>(invert2 '(3 . 4) '(5 . 6))
       ((4 . 3) (6 . 5))
       ACL2 !>(invert2 'a 'b)
       ERROR: INVERT1 expected a cons, but was given A.
       ERROR: INVERT1 expected a cons, but was given B.
       (NIL NIL)
       ACL2 !>

Notice that when there are errors, there is no attempt to explain that
these are due to a call of invert2.  That could be fixed, of course, by
arranging for invert2 to print its own error; but for complicated
programs it can be awkward to coordinate printing from many sources.  So
let's try a different approach.  This time, the first function returns
two results.  The first result is an "error indicator" -- either a
message object or nil -- while the second is the computed value (only of
interest when the first result is nil).  Then the higher-level function
can print a single error message that includes the error message(s)
from the lower-level function, as shown below.


     (defun invert1a (x)
       (if (consp x)
           (mv nil
               (cons (cdr x) (car x)))
         (mv (msg "ERROR: ~x0 expected a cons, but was given ~x1.~|"
                  'invert1a x)
             nil)))

     (defun invert2a (x1 x2)
       (mv-let (erp1 y1)
               (invert1a x1)
               (mv-let (erp2 y2)
                       (invert1a x2)
                       (if erp1
                           (if erp2
                               (cw "~x0 failed with two errors:~|  ~@1  ~@2"
                                   'invert2a erp1 erp2)
                             (cw "~x0 failed with one error:~|  ~@1"
                                 'invert2a erp1))
                         (if erp2
                             (cw "~x0 failed with one error:~|  ~@1"
                                 'invert2a erp2)
                           (list y1 y2))))))

For example:

       ACL2 !>(invert2a '(3 . 4) '(5 . 6))
       ((4 . 3) (6 . 5))
       ACL2 !>(invert2a '(3 . 4) 'b)
       INVERT2A failed with one error:
         ERROR: INVERT1A expected a cons, but was given B.
       NIL
       ACL2 !>(invert2a 'a 'b)
       INVERT2A failed with two errors:
         ERROR: INVERT1A expected a cons, but was given A.
         ERROR: INVERT1A expected a cons, but was given B.
       NIL
       ACL2 !>

If you study the example above, you might well understand msg.  But we
conclude with precise documentation.

     General Form:
     (msg str arg1 ... argk)

where str is a string and k is at most 9.

This macro returns a pair suitable for giving to the fmt directive ~@.
Thus, suppose that #\c is bound to the value of (msg str arg1 ...
argk), where c is a character and k is at most 9.  Then the fmt
directive ~@c will print out the string, str, in the context of the
alist in which the successive fmt variables #\0, #\1, ..., #\k are
bound to the successive elements of (arg1 ... argk).


File: acl2-doc-emacs.info,  Node: MUST-BE-EQUAL,  Next: MV,  Prev: MSG,  Up: ACL2-BUILT-INS

MUST-BE-EQUAL    attach code for execution

The form (must-be-equal logic exec) evaluates to logic in the ACL2
logic but evaluates to exec in raw Lisp.  The point is to be able to
write one definition to reason about logically but another for
evaluation.  Please see *note MBE:: and see *note MBT:: for appropriate
macros to use, rather than calling must-be-equal directly, since it is
easy to commute the arguments of must-be-equal by accident.

In essence, the guard for (must-be-equal x y) is (equal x y).  However,
note that must-be-equal is a macro: (must-be-equal logic exec) expands
to (mbe1 exec logic), which expands to a call of return-last.


File: acl2-doc-emacs.info,  Node: MV,  Next: MV-LET,  Prev: MUST-BE-EQUAL,  Up: ACL2-BUILT-INS

MV    returning a multiple value

Mv is the mechanism provided by ACL2 for returning two or more values.
Logically, (mv x1 x2 ... xn) is the same as (list x1 x2 ... xn), a list
of the indicated values.  However, ACL2 avoids the cost of building this
list structure, with the cost that mv may only be used in a certain
style in definitions: if a function ever returns using mv (either
directly, or by calling another function that returns a multiple
value), then this function must always return the same number of values.

For more explanation of the multiple value mechanism, see *note
MV-LET::.  Also see *note MV-LIST:: for a way to convert a multiple
value into an ordinary list.

ACL2 does not support the Common Lisp construct values, whose logical
meaning seems difficult to characterize.  Mv is the ACL2 analogue of
that construct.


File: acl2-doc-emacs.info,  Node: MV-LET,  Next: MV-LIST,  Prev: MV,  Up: ACL2-BUILT-INS

MV-LET    calling multi-valued ACL2 functions

     Example Form:
     (mv-let (x y z)              ; local variables
             (mv 1 2 3)           ; multi-valued expression
             (declare (ignore y)) ; optional declarations
             (cons x z))          ; body

The form above binds the three "local variables," x, y, and z, to the
three results returned by the multi-valued expression and then
evaluates the body.  The result is '(1 . 3).  The second local, y, is
declared ignored.  The multi-valued expression can be any ACL2
expression that returns k results, where k is the number of local
variables listed.  Often however it is simply the application of a
k-valued function.  Mv-let is the standard way to invoke a multi-valued
function when the caller must manipulate the vector of results returned.

     General Form:
     (mv-let (var1 ... vark)
             term
             body)
     or
     (mv-let (var1 ... vark)
             term
             (declare ...) ... (declare ...)
             body)

where the vari are distinct variables, term is a term that returns k
results and mentions only variables bound in the environment containing
the mv-let expression, and body is a term mentioning only the vari and
variables bound in the environment containing the mv-let.  Each vari
must occur in body unless it is declared ignored or ignorable in one of
the optional declare forms, unless this requirement is turned off; see
*note SET-IGNORE-OK::.  The value of the mv-let term is the result of
evaluating body in an environment in which the vari are bound, in
order, to the k results obtained by evaluating term in the environment
containing the mv-let.

Here is an extended example that illustrates both the definition of a
multi-valued function and the use of mv-let to call it.  Consider a
simple binary tree whose interior nodes are conses and whose leaves are
non-conses.  Suppose we often need to know the number, n, of interior
nodes of such a tree; the list, syms, of symbols that occur as leaves;
and the list, ints, of integers that occur as leaves.  (Observe that
there may be leaves that are neither symbols nor integers.)  Using a
multi-valued function we can collect all three results in one pass.

Here is the first of two definitions of the desired function.  This
definition is "primitive recursive" in that it has only one argument
and that argument is reduced in size on every recursion.

     (defun count-and-collect (x)

     ; We return three results, (mv n syms ints) as described above.

       (cond ((atom x)

     ; X is a leaf.  Thus, there are 0 interior nodes, and depending on
     ; whether x is a symbol, an integer, or something else, we return
     ; the list containing x in as the appropriate result.

              (cond ((symbolp x) (mv 0 (list x) nil))
                    ((integerp x)(mv 0 nil      (list x)))
                    (t           (mv 0 nil      nil))))
             (t

     ; X is an interior node.  First we process the car, binding n1, syms1, and
     ; ints1 to the answers.

                (mv-let (n1 syms1 ints1)
                        (count-and-collect (car x))

     ; Next we process the cdr, binding n2, syms2, and ints2.

                        (mv-let (n2 syms2 ints2)
                                (count-and-collect (car x))

     ; Finally, we compute the answer for x from those obtained for its car
     ; and cdr, remembering to increment the node count by one for x itself.

                                (mv (1+ (+ n1 n2))
                                    (append syms1 syms2)
                                    (append ints1 ints2)))))))

This use of a multiple value to "do several things at once" is very
common in ACL2.  However, the function above is inefficient because it
appends syms1 to syms2 and ints1 to ints2, copying the list structures
of syms1 and ints1 in the process.  By adding "accumulators" to the
function, we can make the code more efficient.

     (defun count-and-collect1 (x n syms ints)
       (cond ((atom x)
              (cond ((symbolp x) (mv n (cons x syms) ints))
                    ((integerp x) (mv n syms (cons x ints)))
                    (t (mv n syms ints))))
             (t (mv-let (n2 syms2 ints2)
                        (count-and-collect1 (cdr x) (1+ n) syms ints)
                        (count-and-collect1 (car x) n2 syms2 ints2)))))

We claim that (count-and-collect x) returns the same triple of results
as (count-and-collect1 x 0 nil nil).  The reader is urged to study this
claim until convinced that it is true and that the latter method of
computing the results is more efficient.  One might try proving the
theorem

     (defthm count-and-collect-theorem
       (equal (count-and-collect1 x 0 nil nil) (count-and-collect x))).

Hint:  the inductive proof requires attacking a more general theorem.

ACL2 does not support the Common Lisp construct multiple-value-bind,
whose logical meaning seems difficult to characterize.  Mv-let is the
ACL2 analogue of that construct.  Also see *note MV:: and see *note
MV-LIST::.


File: acl2-doc-emacs.info,  Node: MV-LIST,  Next: MV-NTH,  Prev: MV-LET,  Up: ACL2-BUILT-INS

MV-LIST    converting multiple-valued result to a single-valued list

     Example Forms:
     ; Returns the list (3 4):
     (mv-list 2 (mv 3 4))

     ; Returns a list containing the three values returned by var-fn-count:
     (mv-list 3 (var-fn-count '(cons (binary-+ x y) z) nil))

     General form:
     (mv-list n term)

Logically, (mv-list n term) is just term; that is, in the logic mv-list
simply returns its second argument.  However, the evaluation of a call
of mv-list on explicit values always results in a single value, which
is a (null-terminated) list.  For evaluation, the term n above (the
first argument to an mv-list call) must "essentially" (see below) be an
integer not less than 2, where that integer is the number of values
returned by the evaluation of term (the second argument to that mv-list
call).

We say "essentially" above because it suffices that the translation of
n to a term (see *note TRANS::) be of the form (quote k), where k is an
integer greater than 1.  So for example, if term above returns three
values, then n can be the expression 3, or (quote 3), or even (mac 3)
if mac is a macro defined by (defmacro mac (x) x).  But n cannot be (+
1 2), because even though that expression evaluates to 3, nevertheless
it translates to (binary-+ '1 '2), not to (quote 3).

Mv-list is the ACL2 analogue of the Common Lisp construct
multiple-value-list.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: MV-NTH,  Next: MV?,  Prev: MV-LIST,  Up: ACL2-BUILT-INS

MV-NTH    the mv-nth element (zero-based) of a list

(Mv-nth n l) is the nth element of l, zero-based.  If n is greater than
or equal to the length of l, then mv-nth returns nil.

(Mv-nth n l) has a guard that n is a non-negative integer.

Mv-nth is equivalent to the Common Lisp function nth (although without
the guard condition that the list is a true-listp), but is used by ACL2
to access the nth value returned by a multiply valued expression.  For
example, the following are logically equivalent:

     (mv-let (erp val state)
             (read-object ch state)
             (value (list erp val)))

and

     (let ((erp (mv-nth 0 (read-object ch state)))
           (val (mv-nth 1 (read-object ch state)))
           (state (mv-nth 2 (read-object ch state))))
       (value (list erp val)))

To see the ACL2 definition of mv-nth, see *note PF::.

If EXPR is an expression that is multiply valued, then the form (mv-nth
n EXPR) is illegal both in definitions and in forms submitted directly
to the ACL2 loop.  Indeed, EXPR cannot be passed as an argument to any
function (mv-nth or otherwise) in such an evaluation context.  The
reason is that ACL2 code compiled for execution does not actually
create a list for multiple value return; for example, the read-object
call above logically returns a list of length 3, but when evaluated, it
instead stores its three returned values without constructing a list.
In such cases you can use mv-nth to access the corresponding list by
using mv-list, writing (mv-nth n (mv-list k EXPR)) for suitable k,
where mv-list converts a multiple value result into the corresponding
list; see *note MV-LIST::.


File: acl2-doc-emacs.info,  Node: MV?,  Next: MV?-LET,  Prev: MV-NTH,  Up: ACL2-BUILT-INS

MV?    return one or more values

Mv? is designed to work with mv?-let, generalizing how mv works with
mv-let by allowing the binding of a single variable.  For example, the
following form is legal.

     (mv?-let (y)
              (mv? (f x))
              (declare (type integer y))
              (g x y z))

The expression above is equivalent to the following expression, because
(mv? form) expands to form for any expression, form.

     (let ((y (f x)))
       (declare (type integer y))
       (g x y z))

Logically, (mv? x) is the same as x, while (mv? v1 v2 ...) is the same
as (list v1 v2 ...).  Also see *note MV:: and see *note MV?-LET::.


File: acl2-doc-emacs.info,  Node: MV?-LET,  Next: NAT-LISTP,  Prev: MV?,  Up: ACL2-BUILT-INS

MV?-LET    calling possibly multi-valued ACL2 functions

Mv?-let is a macro that extends the macro mv-let by allowing a single
variable to be bound.  Thus, the syntax is the same as that of mv-let
except that mv?-let is permitted to bind a single variable to a form
that produces a single value.  The macros mv?-let and mv?  are provided
to facilitate the writing of macros that traffic in expressions that
could return one or more (multiple) values.

For example, the form

     (mv?-let (y)
              (f x)
              (declare (type integer y))
              (g x y z))

is equivalent to the following form.

     (let ((y (f x)))
       (declare (type integer y))
       (g x y z))

Calls of mv?-let and of mv-let are equivalent when the first argument
contains at least two variables; see *note MV-LET:: for documentation.
In the case of binding a single variable, the general form is

     (mv?-let (var)
              term
              (declare ...) ... (declare ...)
              body)

and this is equivalent to the following form (see *note LET::).

     (let ((var term))
       (declare ...) ... (declare ...)
       body)

Also see *note MV?::.


File: acl2-doc-emacs.info,  Node: NAT-LISTP,  Next: NATP,  Prev: MV?-LET,  Up: ACL2-BUILT-INS

NAT-LISTP    recognizer for a true list of natural  numbers

The predicate nat-listp tests whether its argument is a true list of
natural numbers.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: NATP,  Next: NFIX,  Prev: NAT-LISTP,  Up: ACL2-BUILT-INS

NATP    a recognizer for the natural numbers

The natural numbers is the set of all non-negative integers,
{0,1,2,3,...}.  Natp returns t if and only its argument is a   natural
number, and nil otherwise.  We recommend the community book
books/arithmetic/natp-posp.lisp as a book for reasoning about posp
and natp.  This book is included by community books
books/arithmetic/top and books/arithmetic/top-with-meta.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: NFIX,  Next: NINTH,  Prev: NATP,  Up: ACL2-BUILT-INS

NFIX    coerce to a natural number

Nfix simply returns any natural number argument unchanged, returning 0
on an argument that is not a natural number.  Also see *note IFIX::,
see *note RFIX::, see *note REALFIX::, and see *note FIX:: for
analogous functions that coerce to an integer, a rational number, a
real, and a number, respectively.

Nfix has a guard of t.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: NINTH,  Next: NO-DUPLICATESP,  Prev: NFIX,  Up: ACL2-BUILT-INS

NINTH    ninth member of the list

See any Common Lisp documentation for details.


File: acl2-doc-emacs.info,  Node: NO-DUPLICATESP,  Next: NO-DUPLICATESP-EQ,  Prev: NINTH,  Up: ACL2-BUILT-INS

NO-DUPLICATESP    check for duplicates in a list

     General Forms:
     (no-duplicatesp x)
     (no-duplicatesp x :test 'eql)   ; same as above (eql as equality test)
     (no-duplicatesp x :test 'eq)    ; same, but eq is equality test
     (no-duplicatesp x :test 'equal) ; same, but equal is equality test

(no-duplicatesp lst) is true if and only if no member of lst occurs
twice in lst.  The optional keyword, :TEST, has no effect logically,
but provides the test (default eql) used for comparing elements of lst.

The guard for a call of no-duplicatesp depends on the test.  In all
cases, the argument must satisfy true-listp.  If the test is eql, then
the argument must satisfy eqlable-listp.  If the test is eq, then the
argument must satisfy symbol-listp.

See *note EQUALITY-VARIANTS:: for a discussion of the relation between
no-duplicatesp and its variants:

     (no-duplicatesp-eq x lst) is equivalent to (no-duplicatesp x lst
     :test 'eq);

     (no-duplicatesp-equal x lst) is equivalent to (no-duplicatesp x
     lst :test 'equal).


In particular, reasoning about any of these primitives reduces to
reasoning about the function no-duplicatesp-equal.


File: acl2-doc-emacs.info,  Node: NO-DUPLICATESP-EQ,  Next: NO-DUPLICATESP-EQUAL,  Prev: NO-DUPLICATESP,  Up: ACL2-BUILT-INS

NO-DUPLICATESP-EQ    See *note NO-DUPLICATESP::.


File: acl2-doc-emacs.info,  Node: NO-DUPLICATESP-EQUAL,  Next: NON-EXEC,  Prev: NO-DUPLICATESP-EQ,  Up: ACL2-BUILT-INS

NO-DUPLICATESP-EQUAL    See *note NO-DUPLICATESP::.


File: acl2-doc-emacs.info,  Node: NON-EXEC,  Next: NONNEGATIVE-INTEGER-QUOTIENT,  Prev: NO-DUPLICATESP-EQUAL,  Up: ACL2-BUILT-INS

NON-EXEC    mark code as non-executable

Non-exec is a macro such that logically, (non-exec x) is equal to x.
However, the argument to a call of non-exec need not obey the usual
syntactic restrictions for executable code, and indeed, evaluation of a
call of non-exec will result in an error.  Moreover, for any form
occurring in the body of a function (see *note DEFUN::) that is a call
of non-exec, no guard proof obligations are generated for that form.

The following example, although rather contrived, illustrates the use of
non-exec.  One can imagine a less contrived example that efficiently
computes return values for a small number of fixed inputs and, for other
inputs, returns something logically "consistent" with those return
values.

     (defun double (x)
       (case x
         (1 2)
         (2 4)
         (3 6)
         (otherwise (non-exec (* 2 x)))))

We can prove that double is compliant with Common Lisp (see *note
GUARD::) and that it always computes (* 2 x).

     (verify-guards double)
     (thm (equal (double x) (* 2 x)))

We can evaluate double on the specified arguments.  But a call of
non-exec results in an error message that reports the form that was
supplied to non-exec.

     ACL2 !>(double 3)
     6
     ACL2 !>(double 10)


     ACL2 Error in TOP-LEVEL:  ACL2 has been instructed to cause an error
     because of an attempt to evaluate the following form (see :DOC non-
     exec):

       (* 2 X).

     To debug see :DOC print-gv, see :DOC trace, and see :DOC wet.

     ACL2 !>

During proofs, the error is silent; it is "caught" by the proof
mechanism and generally results in the introduction of a call of hide
during a proof.

Also see *note DEFUN-NX:: for a utility that makes every call of a
function non-executable, rather than a specified form.  The following
examples contrast non-exec with defun-nx, in particular illustratating
the role of non-exec in avoiding guard proof obligations.

     ; Guard verification fails:
     (defun-nx f1 (x)
       (declare (xargs :guard t))
       (car x))

     ; Guard verification succeeds after changing the guard above:
     (defun-nx f1 (x)
       (declare (xargs :guard (consp x)))
       (car x))

     ; Guard verification succeeds:
     (defun f2 (x)
       (declare (xargs :guard t))
       (non-exec (car x)))

     ; Evaluating (g1) prints "Hello" before signaling an error.
     (defun g1 ()
       (f1 (cw "Hello")))

     ; Evaluating (g2) does not print before signaling an error.
     (defun g2 ()
       (non-exec (cw "Hello")))

     ; Evaluating (h1) gives a guard violation for taking reciprocal of 0.
     (defun h1 ()
       (f1 (/ 1 0)))

     ; Evaluating (h2) does not take a reciprocal, hence there is no guard
     ; violation for that; we just get the error expected from using non-exec.
     (defun h2 ()
       (non-exec (/ 0)))


File: acl2-doc-emacs.info,  Node: NONNEGATIVE-INTEGER-QUOTIENT,  Next: NOT,  Prev: NON-EXEC,  Up: ACL2-BUILT-INS

NONNEGATIVE-INTEGER-QUOTIENT    natural number division function

     Example Forms:
     (nonnegative-integer-quotient 14 3) ; equals 4
     (nonnegative-integer-quotient 15 3) ; equals 5

(nonnegative-integer-quotient i j) returns the integer quotient of the
integers i and (non-zero) j, i.e., the largest k such that (* j k) is
less than or equal to i.  Also see *note FLOOR::, see *note CEILING::
and see *note TRUNCATE::, which are derived from this function and
apply to rational numbers.

The guard of (nonnegative-integer-quotient i j) requires that i is a
nonnegative integer and j is a positive integer.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: NOT,  Next: NTH,  Prev: NONNEGATIVE-INTEGER-QUOTIENT,  Up: ACL2-BUILT-INS

NOT    logical negation

Not is the ACL2 negation function.  The negation of nil is t and the
negation of anything else is nil.

Not is a Common Lisp function.  See any Common Lisp documentation for
more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: NTH,  Next: NTHCDR,  Prev: NOT,  Up: ACL2-BUILT-INS

NTH    the nth element (zero-based) of a list

(Nth n l) is the nth element of l, zero-based.  If n is greater than or
equal to the length of l, then nth returns nil.

(Nth n l) has a guard that n is a non-negative integer and l is a
true-listp.

Nth is a Common Lisp function.  See any Common Lisp documentation for
more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: NTHCDR,  Next: NULL,  Prev: NTH,  Up: ACL2-BUILT-INS

NTHCDR    final segment of a list

(Nthcdr n l) removes the first n elements from the list l.

The following is a theorem.

     (implies (and (integerp n)
                   (<= 0 n)
                   (true-listp l))
              (equal (length (nthcdr n l))
                     (if (<= n (length l))
                         (- (length l) n)
                       0)))

For related functions, see *note TAKE:: and see *note BUTLAST::.

The guard of (nthcdr n l) requires that n is a nonnegative integer and
l is a true list.

Nthcdr is a Common Lisp function.  See any Common Lisp documentation
for more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: NULL,  Next: NUMERATOR,  Prev: NTHCDR,  Up: ACL2-BUILT-INS

NULL    recognizer for the empty list

Null is the function that checks whether its argument is nil.  For
recursive definitions it is often preferable to test for the end of a
list using endp instead of null; see *note ENDP::.

Null is a Common Lisp function.  See any Common Lisp documentation for
more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: NUMERATOR,  Next: O-FINP,  Prev: NULL,  Up: ACL2-BUILT-INS

NUMERATOR    dividend of a ratio in lowest terms

Completion Axiom (completion-of-numerator):

     (equal (numerator x)
            (if (rationalp x)
                (numerator x)
              0))

Guard for (numerator x):

     (rationalp x)


File: acl2-doc-emacs.info,  Node: O-FINP,  Next: O-FIRST-COEFF,  Prev: NUMERATOR,  Up: ACL2-BUILT-INS

O-FINP    recognizes if an ordinal is finite

We introduce the function o-finp which returns t for any ordinal that
is finite, else nil.  This function is equivalent to the function atom,
and is introduced so that we can disable its definition when dealing
with ordinals (also see *note MAKE-ORD::).

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: O-FIRST-COEFF,  Next: O-FIRST-EXPT,  Prev: O-FINP,  Up: ACL2-BUILT-INS

O-FIRST-COEFF    returns the first coefficient of an ordinal

An ACL2 ordinal is either a natural number or, for an infinite ordinal,
a list whose elements are exponent-coefficient pairs (see *note O-P::).
In the latter case, this function returns the cdr of the first pair in
the list.  In the case of a natural number, this function returns the
ordinal itself (since a natural number, n, can be thought of as (w^0)n).

For the corresponding exponent, see *note O-FIRST-EXPT::.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: O-FIRST-EXPT,  Next: O-INFP,  Prev: O-FIRST-COEFF,  Up: ACL2-BUILT-INS

O-FIRST-EXPT    the first exponent of an ordinal

An ACL2 ordinal is either a natural number or, for an infinite ordinal,
a list whose elements are exponent-coefficient pairs (see *note O-P::).
In the latter case, this function returns the car of the first pair in
the list.  In the case of a natural number, the value returned is 0
(since a natural number, n, can be thought of as (w^0)n).

For the corresponding coefficient, see *note O-FIRST-COEFF::.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: O-INFP,  Next: O-P,  Prev: O-FIRST-EXPT,  Up: ACL2-BUILT-INS

O-INFP    recognizes if an ordinal is infinite

O-infp is a macro.  (O-infp x) opens up to (not (o-finp x)) (see *note
O-FINP::).


File: acl2-doc-emacs.info,  Node: O-P,  Next: O-RST,  Prev: O-INFP,  Up: ACL2-BUILT-INS

O-P    a recognizer for the ordinals up to epsilon-0

Using the nonnegative integers and lists we can represent the ordinals
up to epsilon-0. The ordinal representation used in ACL2 has changed as
of Version_2.8 from that of Nqthm-1992, courtesy of Pete Manolios and
Daron Vroon; additional discussion may be found in "Ordinal Arithmetic
in ACL2", proceedings of ACL2 Workshop 2003,
`http://www.cs.utexas.edu/users/moore/acl2/workshop-2003/'.  Previously,
ACL2's notion of ordinal was very similar to the development given in
"New Version of the Consistency Proof for Elementary Number Theory" in
The Collected Papers of Gerhard Gentzen, ed. M.E. Szabo, North-Holland
Publishing Company, Amsterdam, 1969, pp 132-213.

The following essay is intended to provide intuition about ordinals.
The truth, of course, lies simply in the ACL2 definitions of o-p and o<.

Very intuitively, think of each non-zero natural number as by being
denoted by a series of the appropriate number of strokes, i.e.,

     0             0
     1             |
     2             ||
     3             |||
     4             ||||
     ...           ...

Then "omega," here written as w, is the ordinal that might be written as

     w             |||||...,

i.e., an infinite number of strokes.  Addition here is just
concatenation.  Observe that adding one to the front of w in the
picture above produces w again, which gives rise to a standard
definition of w:  w is the least ordinal such that adding another
stroke at the beginning does not change the ordinal.

We denote by w+w or w*2 the "doubly infinite" sequence that we might
write as follows.

     w*2           |||||... |||||...

One way to think of w*2 is that it is obtained by replacing each stroke
in 2 (||) by w.  Thus, one can imagine w*3, w*4, etc., which leads
ultimately to the idea of "w*w," the ordinal obtained by replacing each
stroke in w by w.  This is also written as "omega squared" or w^2, or:

      2
     w             |||||... |||||... |||||... |||||... |||||... ...

We can analogously construct w^3 by replacing each stroke in w by w^2
(which, it turns out, is the same as replacing each stroke in w^2 by
w).  That is, we can construct w^3 as w copies of w^2,

      3              2       2       2       2
     w              w  ...  w  ...  w  ...  w ... ...

Then we can construct w^4 as w copies of w^3, w^5 as w copies of w^4,
etc., ultimately suggesting w^w.  We can then stack omegas, i.e.,
(w^w)^w etc.  Consider the "limit" of all of those stacks, which we
might display as follows.

            .
           .
          .
         w
        w
       w
      w
     w

That is epsilon-0.

Below we begin listing some ordinals up to epsilon-0; the reader can
fill in the gaps at his or her leisure.  We show in the left column the
conventional notation, using w as "omega," and in the right column the
ACL2 object representing the corresponding ordinal.

       ordinal            ACL2 representation

       0                  0
       1                  1
       2                  2
       3                  3
       ...                ...
       w                 '((1 . 1) . 0)
       w+1               '((1 . 1) . 1)
       w+2               '((1 . 1) . 2)
       ...                ...
       w*2               '((1 . 2) . 0)
       (w*2)+1           '((1 . 2) . 1)
       ...                ...
       w*3               '((1 . 3) . 0)
       (w*3)+1           '((1 . 3) . 1)
       ...                ...

        2
       w                 '((2 . 1) . 0)
       ...                ...

        2
       w +w*4+3          '((2 . 1) (1 . 4) . 3)
       ...                ...

        3
       w                 '((3 . 1) . 0)
       ...                ...


        w
       w                 '((((1 . 1) . 0) . 1) . 0)
       ...                ...

        w  99
       w +w  +w4+3       '((((1 . 1) . 0) . 1) (99 . 1) (1 . 4) . 3)
       ...                ...

         2
        w
       w                 '((((2 . 1) . 0) . 1) . 0)

       ...                ...

         w
        w
       w                 '((((((1 . 1) . 0) . 1) . 0) . 1) . 0)
       ...               ...

Observe that the sequence of o-ps starts with the natural numbers
(which are recognized by natp). This is convenient because it means
that if a term, such as a measure expression for justifying a recursive
function (see *note O<::) must produce an o-p, it suffices for it to
produce a natural number.

The ordinals listed above are listed in ascending order.  This is the
ordering tested by o<.

The "epsilon-0 ordinals" of ACL2 are recognized by the recursively
defined function o-p.  The base case of the recursion tells us that
natural numbers are epsilon-0 ordinals.  Otherwise, an epsilon-0
ordinal is a list of cons pairs whose final cdr is a natural number,
((a1 . x1) (a2 . x2) ... (an . xn) . p).  This corresponds to the
ordinal (w^a1)x1 + (w^a2)x2 + ... + (w^an)xn + p.  Each ai is an
ordinal in the ACL2 representation that is not equal to 0.  The
sequence of the ai's is strictly decreasing (as defined by o<). Each xi
is a positive integer (as recognized by posp).

Note that infinite ordinals should generally be created using the
ordinal constructor, make-ord, rather than cons. The functions
o-first-expt, o-first-coeff, and o-rst are ordinals destructors.
Finally, the function o-finp and the macro o-infp tell whether an
ordinal is finite or infinite, respectively.

The function o< compares two epsilon-0 ordinals, x and y.  If both are
integers, (o< x y) is just x<y.  If one is an integer and the other is
a cons, the integer is the smaller.  Otherwise, o< recursively compares
the o-first-expts of the ordinals to determine which is smaller.  If
they are the same, the o-first-coeffs of the ordinals are compared.  If
they are equal, the o-rsts of the ordinals are recursively compared.

Fundamental to ACL2 is the fact that o< is well-founded on epsilon-0
ordinals.  That is, there is no "infinitely descending chain" of such
ordinals.  See *note PROOF-OF-WELL-FOUNDEDNESS::.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: O-RST,  Next: O<,  Prev: O-P,  Up: ACL2-BUILT-INS

O-RST    returns the rest of an infinite ordinal

An ACL2 infinite ordinal is a list whose elements are
exponent-coefficient pairs (see *note O-P:: and see *note O-INFP::).
The first exponent and first coefficient of an ordinal can be obtained
by using o-first-expt and o-first-coeff respectively.  To obtain the
rest of the ordinal (for recursive analysis), use the o-rst function.
It returns the rest of the ordinal after the first exponent and
coefficient are removed.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: O<,  Next: O<=,  Prev: O-RST,  Up: ACL2-BUILT-INS

O<    the well-founded less-than relation on ordinals up to epsilon-0

If x and y are both o-ps (see *note O-P::) then (o< x y) is true iff x
is strictly less than y.  o< is well-founded on the o-ps.  When x and y
are both nonnegative integers, o< is just the familiar "less than"
relation (<).

o< plays a key role in the formal underpinnings of the ACL2 logic.  In
order for a recursive definition to be admissible it must be proved to
"terminate."  By terminate we mean that the arguments to the function
"get smaller" as the function recurses and this sense of size
comparison must be such that there is no "infinitely descending"
sequence of ever smaller arguments.  That is, the relation used to
compare successive arguments must be well-founded on the domain being
measured.

The most basic way ACL2 provides to prove termination requires the user
to supply (perhaps implicitly) a mapping of the argument tuples into
the ordinals with some "measure" expression in such a way that the
measures of the successive argument tuples produced by recursion
decrease according to the relation o<.  The validity of this method
rests on the well-foundedness of o< on the o-ps.

Without loss of generality, suppose the definition in question
introduces the function f, with one formal parameter x (which might be
a list of objects).  Then we require that there exist a measure
expression, (m x), that always produces an o-p.  Furthermore, consider
any recursive call, (f (d x)), in the body of the definition.  Let hyps
be the conjunction of terms, each of which is either the test of an if
in the body or else the negation of such a test, describing the path
through the body to the recursive call in question.  Then it must be a
theorem that

       (IMPLIES hyps (O< (m (d x)) (m x))).

When we say o< is "well-founded" on the o-ps we mean that there is no
infinite sequence of o-ps such that each is smaller than its
predecessor in the sequence.  Thus, the theorems that must be proved
about f when it is introduced establish that it cannot recur forever
because each time a recursive call is taken (m x) gets smaller.  From
this, and the syntactic restrictions on definitions, it can be shown
(as on page 44 in "A Computational Logic", Boyer and Moore, Academic
Press, 1979) that there exists a function satisfying the definition;
intuitively, the value assigned to any given x by the alleged function
is that computed by a sufficiently large machine.  Hence, the logic is
consistent if the axiom defining f is added.

See *note O-P:: for a discussion of the ordinals and how to compare two
ordinals.

The definitional principle permits the use of relations other than o<
but they must first be proved to be well-founded on some domain.  See
*note WELL-FOUNDED-RELATION::.  Roughly put, alternative relations are
shown well-founded by providing an order-preserving mapping from their
domain into the ordinals.  See *note DEFUN:: for details on how to
specify which well-founded relation is to be used.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: O<=,  Next: O>,  Prev: O<,  Up: ACL2-BUILT-INS

O<=    the less-than-or-equal relation for the ordinals

o<= is a macro and (o<= x y) expands to (not (o< y x)).  See *note O<::.


File: acl2-doc-emacs.info,  Node: O>,  Next: O>=,  Prev: O<=,  Up: ACL2-BUILT-INS

O>    the greater-than relation for the ordinals

O> is a macro and (o> x y) expands to (o< y x).  See *note O<::.


File: acl2-doc-emacs.info,  Node: O>=,  Next: OBSERVATION,  Prev: O>,  Up: ACL2-BUILT-INS

O>=    the greater-than-or-equal relation for the ordinals

O>= is a macro and (o>= x y) expands to (not (o< x y)).  See *note O<::.


File: acl2-doc-emacs.info,  Node: OBSERVATION,  Next: OBSERVATION-CW,  Prev: O>=,  Up: ACL2-BUILT-INS

OBSERVATION    print an observation

Here is a typical application of observation.

     ACL2 !>(let ((ctx 'top-level)
                  (name 'foo))
              (observation ctx
                           "Skipping processing of name ~x0."
                           name))

     ACL2 Observation in TOP-LEVEL:  Skipping processing of name FOO.
     <state>
     ACL2 !>

Observation prints an initial "ACL2 Observation...:  ", and then prints
the indicated message using formatted printing (see *note FMT::).
Notice in the example above that evaluation of a call of observation
returns state.  Indeed, observation is actually a macro whose expansion
takes and returns the ACL2 state.  A similar utility, observation-cw,
is available that does not take or return state; rather, it returns nil
as the suffix "cw" suggests that a "comment window" is the target of
this printing, rather than the state.  For example:

     ACL2 !>(let ((ctx 'top-level)
                  (name 'foo))
              (observation-cw ctx
                              "Skipping processing of name ~x0."
                              name))

     ACL2 Observation in TOP-LEVEL:  Skipping processing of name FOO.
     NIL
     ACL2 !>

Observation-cw takes exactly the same arguments as observation, but
observation-cw does its printing in a so-called "wormhole"; see *note
WORMHOLE::.

     General Forms:
     (observation    ctx fmt-string fmt-arg1 fmt-arg2 ... fmt-argk)
     (observation-cw ctx fmt-string fmt-arg1 fmt-arg2 ... fmt-argk)

where ctx generally evaluates to a symbol (but see below), and
fmt-string together with the fmt-argi are suitable for passing to fmt.
Output begins and ends with a newline.

Recall from the example above that the output from a call of observation
(or observation-cw) begins with "ACL2 Observation" and additional
characters ending in ":  ", for example " in TOP-LEVEL:  ", followed by
formatted output produced from fmt-string with the given fmt-argi.  The
characters printed immediately following the string "ACL2 Observation"
depend on the value of ctx.  If ctx is nil, nothing is printed.  If ctx
is a non-nil symbol, it is printed using fmt directive ~x.  If ctx is a
cons pair whose car is a symbol, formatted printing is applied to the
string "(~x0 ~x1 ...)", where #\0 and #\1 are bound respectively to
that car and cdr.  Otherwise, ctx is printed using fmt directive ~@.

We next discuss situations in which printing is inhibited for
observation and observation-cw.  No printing is done when observation
is among the inhibited output types; see *note
SET-INHIBIT-OUTPUT-LST::.  Moreover, no printing is done by observation
during include-book.  If you want to avoid printing from observation-cw
during include-book, then you need to manage that yourself.


File: acl2-doc-emacs.info,  Node: OBSERVATION-CW,  Next: ODDP,  Prev: OBSERVATION,  Up: ACL2-BUILT-INS

OBSERVATION-CW    See *note OBSERVATION::.


File: acl2-doc-emacs.info,  Node: ODDP,  Next: OPEN-INPUT-CHANNEL,  Prev: OBSERVATION-CW,  Up: ACL2-BUILT-INS

ODDP    test whether an integer is odd

(oddp x) is true if and only if x is odd, i.e., not even in the sense
of evenp.

The guard for oddp requires its argument to be an integer.

Oddp is a Common Lisp function.  See any Common Lisp documentation for
more information.

To see the ACL2 definition of this function, see *note PF::.


File: acl2-doc-emacs.info,  Node: OPEN-INPUT-CHANNEL,  Next: OPEN-INPUT-CHANNEL-P,  Prev: ODDP,  Up: ACL2-BUILT-INS

OPEN-INPUT-CHANNEL    See *note IO::.


File: acl2-doc-emacs.info,  Node: OPEN-INPUT-CHANNEL-P,  Next: OPEN-OUTPUT-CHANNEL,  Prev: OPEN-INPUT-CHANNEL,  Up: ACL2-BUILT-INS

OPEN-INPUT-CHANNEL-P    See *note IO::.


File: acl2-doc-emacs.info,  Node: OPEN-OUTPUT-CHANNEL,  Next: OPEN-OUTPUT-CHANNEL-P,  Prev: OPEN-INPUT-CHANNEL-P,  Up: ACL2-BUILT-INS

OPEN-OUTPUT-CHANNEL    See *note IO::.


File: acl2-doc-emacs.info,  Node: OPEN-OUTPUT-CHANNEL-P,  Next: OR,  Prev: OPEN-OUTPUT-CHANNEL,  Up: ACL2-BUILT-INS

OPEN-OUTPUT-CHANNEL-P    See *note IO::.


File: acl2-doc-emacs.info,  Node: OR,  Next: ORACLE-APPLY,  Prev: OPEN-OUTPUT-CHANNEL-P,  Up: ACL2-BUILT-INS

OR    disjunction

Or is the macro for disjunctions.  Or takes any number of arguments and
returns the first that is non-nil, or nil if there is no non-nil
element.

In the ACL2 logic, the macroexpansion of (or x y) is an IF term that
appears to cause x to be evaluated twice:

     ACL2 !>:trans (or x y)

     (IF X X Y)

     => *

     ACL2 !>

If x were replaced by an expression whose evaluation takes a long time,
then such an expansion would be ineffecient.  However, don't be fooled:
you can expect Common Lisp implementations to avoid this problem, say by
generating a new variable, for example:

     ACL2 !>:q ; Exit the ACL2 loop and go into raw Common Lisp

     Exiting the ACL2 read-eval-print loop.  To re-enter, execute (LP).
     ACL2>(macroexpand '(or x y))

     (LET ((#:G5374 X)) (IF #:G5374 #:G5374 Y))
     T

     ACL2>

Or is a Common Lisp macro.  See any Common Lisp documentation for more
information.

