acl2-doc

(in-package "ACL2")

(defxdoc *
  :parents (numbers acl2-built-ins)
  :short "Multiplication macro"
  :long "<p>@('*') is really a macro that expands to calls of the function
 @(tsee binary-*).  So for example</p>

 @({
  (* x y 4 z)
 })

 <p>represents the same term as</p>

 @({
  (binary-* x (binary-* y (binary-* 4 z))).
 })

 <p>See @(see binary-*).</p>

 <p>@('*') is a Common Lisp function.  See any Common Lisp documentation for
 more information.</p>")

(defxdoc *acl2-exports*
  :parents (packages acl2-built-ins)
  :short "Symbols that are often imported into new @(see packages) to provide
 easy access to ACL2 functionality."
  :long "<p>When you define a new package for your own work with @(see defpkg),
 you will usually want to import many symbols from the @('"ACL2"') package;
 for instance you will usually want to be able to use symbols like @(see
 defthm), @(see in-theory), @(see xargs), @(see state), etc., without an
 @('acl2::') prefix.</p>

 <p>The constant @('*acl2-exports*') lists @(`(len *acl2-exports*)`) symbols,
 including most documented ACL2 system constants, functions, and macros.  You
 will typically also want to import many symbols from Common Lisp; see @(see
 *common-lisp-symbols-from-main-lisp-package*).</p>

 <p>Those who write code using built-in ACL2 functions (see @(see
 acl2-built-ins)) may wish to import symbols into their package from the large
 list @(tsee *acl2-system-exports*).</p>

 @(`(:code *acl2-exports*)`)")

(defxdoc *common-lisp-symbols-from-main-lisp-package*
  :parents (packages acl2-built-ins)
  :short "Symbols that are often imported into new packages to provide easy
 access to Common Lisp functionality."
  :long "<p>When you define a new package for your own work with @(see defpkg),
 you will usually want to import many symbols from the @('"COMMON-LISP"')
 package so that you can access them without a @('common-lisp::') or @('acl2::')
 prefix.</p>

 <p>The constant @('*common-lisp-symbols-from-main-lisp-package*') lists the
 @(`(len *common-lisp-symbols-from-main-lisp-package*)`) symbols of the
 @('COMMON-LISP') package found in <a
 href='http://dx.doi.org/10.1145/147135.147249'>dpAns</a>.  You will typically
 also want to import many symbols from ACL2; see @(see *acl2-exports*).</p>

 @(`(:code *common-lisp-symbols-from-main-lisp-package*)`)")

(defxdoc *standard-ci*
  :parents (io acl2-built-ins)
  :short "An ACL2 character-based analogue of CLTL's @('*standard-input*')"
  :long "<p>The value of the ACL2 constant @('*standard-ci*') is an open
 character input channel that is synonymous to Common Lisp's
 @('*standard-input*').</p>

 <p>ACL2 character input from @('*standard-ci*') is actually obtained by
 reading @(see characters) from the stream named by Common Lisp's
 @('*standard-input*').  That is, by changing the setting of
 @('*standard-input*') in raw Common Lisp you can change the source from which
 ACL2 reads on the channel @('*standard-ci*').  See @(see *standard-co*).</p>")

(defxdoc *standard-co*
  :parents (io acl2-built-ins)
  :short "The ACL2 analogue of CLTL's @('*standard-output*')"
  :long "<p>The value of the ACL2 constant @('*standard-co*') is an open
 character output channel that is synonymous to Common Lisp's
 @('*standard-output*').</p>

 <p>ACL2 character output to @('*standard-co*') will go to the stream named by
 Common Lisp's @('*standard-output*').  That is, by changing the setting of
 @('*standard-output*') in raw Common Lisp you can change the actual
 destination of ACL2 output on the channel named by @('*standard-co*').
 Observe that this happens without changing the logical value of
 @('*standard-co*') (which is some channel symbol).  Changing the setting of
 @('*standard-output*') in raw Common Lisp essentially just changes the map
 that relates ACL2 to the physical world of terminals, files, etc.</p>

 <p>To see the value of this observation, consider the following.  Suppose you
 write an ACL2 function which does character output to the constant channel
 @('*standard-co*').  During testing you see that the output actually goes to
 your terminal.  Can you use the function to output to a file?  Yes, if you are
 willing to do a little work in raw Common Lisp: open a stream to the file in
 question, set @('*standard-output*') to that stream, call your ACL2 function,
 and then close the stream and restore @('*standard-output*') to its nominal
 value.  Similar observations can be made about the two ACL2 input channels,
 @(tsee *standard-oi*) and @(tsee *standard-ci*), which are analogues of
 @('*standard-input*').</p>

 <p>Another reason you might have for wanting to change the actual streams
 associated with @(tsee *standard-oi*) and @('*standard-co*') is to drive the
 ACL2 top-level loop, @(tsee ld), on alternative input and output streams.
 This end can be accomplished easily within ACL2 by either calling @(tsee ld)
 on the desired channels or file names or by resetting the ACL2 @(tsee state)
 global variables @(''')@(tsee standard-oi) and @(''')@(tsee standard-co) which
 are used by @(tsee ld).  See @(see standard-oi) and see @(see
 standard-co).</p>")

(defxdoc *standard-oi*
  :parents (io acl2-built-ins)
  :short "An ACL2 object-based analogue of CLTL's @('*standard-input*')"
  :long "<p>The value of the ACL2 constant @('*standard-oi*') is an open object
 input channel that is synonymous to Common Lisp's @('*standard-input*').</p>

 <p>ACL2 object input from @('*standard-oi*') is actually obtained by reading
 from the stream named by Common Lisp's @('*standard-input*').  That is, by
 changing the setting of @('*standard-input*') in raw Common Lisp you can
 change the source from which ACL2 reads on the channel @('*standard-oi*').
 See @(see *standard-co*).</p>")

(defxdoc +
  :parents (numbers acl2-built-ins)
  :short "Addition macro"
  :long "<p>@('+') is really a macro that expands to calls of the function
 @(tsee binary-+).  So for example</p>

 @({
  (+ x y 4 z)
 })

 <p>represents the same term as</p>

 @({
  (binary-+ x (binary-+ y (binary-+ 4 z))).
 })

 <p>See @(see binary-+).</p>

 @(def +)")

(defxdoc -
  :parents (numbers acl2-built-ins)
  :short "Macro for subtraction and negation"
  :long "<p>See @(see binary-+) for addition and see @(see unary--) for
 negation.</p>

 <p>Note that @('-') represents subtraction as follows:</p>

 @({
  (- x y)
 })

 <p>represents the same term as</p>

 @({
  (+ x (- y))
 })

 <p>which is really</p>

 @({
  (binary-+ x (unary-- y)).
 })

 <p>Also note that @('-') represents arithmetic negation as follows:</p>

 @({
  (- x)
 })

 <p>expands to</p>

 @({
  (unary-- x).
 })

 @(def -)")

(defxdoc /
  :parents (numbers acl2-built-ins)
  :short "Macro for division and reciprocal"
  :long "<p>See @(see binary-*) for multiplication and see @(see unary-/) for
 reciprocal.</p>

 <p>Note that @('/') represents division as follows:</p>

 @({
  (/ x y)
 })

 <p>represents the same term as</p>

 @({
  (* x (/ y))
 })

 <p>which is really</p>

 @({
  (binary-* x (unary-/ y)).
 })

 <p>Also note that @('/') represents reciprocal as follows:</p>

 @({
  (/ x)
 })

 <p>expands to</p>

 @({
  (unary-/ x).
 })

 <p>@('/') is a Common Lisp macro.  See any Common Lisp documentation for more
 information.</p>

 @(def /)")

(defxdoc /=
  :parents (numbers acl2-built-ins)
  :short "Test inequality of two numbers"
  :long "<p>@('(/= x y)') is logically equivalent to @('(not (equal x
  y))').</p>

 <p>Unlike @(tsee equal), @('/=') has a @(see guard) requiring both of its
 arguments to be numbers.  Generally, @('/=') is executed more efficiently than
 a combination of @(tsee not) and @(tsee equal).</p>

 <p>For a discussion of the various ways to test against 0, See @(see
 zero-test-idioms).</p>

 <p>@('/=') is a Common Lisp function.  See any Common Lisp documentation for
 more information.</p>

 @(def /=)")

(defxdoc 1+
  :parents (numbers acl2-built-ins)
  :short "Increment by 1"
  :long "<p>@('(1+ x)') is the same as @('(+ 1 x)').  See @(see +).</p>

 <p>@('1+') is a Common Lisp function.  See any Common Lisp documentation for
 more information.</p>

 @(def 1+)")

(defxdoc 1-
  :parents (numbers acl2-built-ins)
  :short "Decrement by 1"
  :long "<p>@('(1- x)') is the same as @('(- x 1)').  See @(see -).</p>

 <p>@('1-') is a Common Lisp function.  See any Common Lisp documentation for
 more information.</p>

 @(def 1-)")

(defxdoc <
  :parents (numbers acl2-built-ins)
  :short "Less-than"
  :long "<p>Completion Axiom (@('completion-of-<')):</p>

 @({
  (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)))))))
 })

 <p>@(see Guard) for @('(< x y)'):</p>

 @({
  (and (rationalp x) (rationalp y))
 })

 <p>Notice that like all arithmetic functions, @('<') treats non-numeric inputs
 as @('0'). Thus, the following are theorems.</p>

 @({
  (thm (equal (< (fix x) y) (< x y)))
  (thm (equal (< x (fix y)) (< x y)))
 })

 <p>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.</p>")

(defxdoc <=
  :parents (numbers acl2-built-ins)
  :short "Less-than-or-equal test"
  :long "<p>@('<=') is a macro, and @('(<= x y)') expands to the same thing as
 @('(not (< y x))').  See @(see <).</p>

 <p>@('<=') is a Common Lisp function.  See any Common Lisp documentation for
 more information.</p>

 @(def <=)")

(defxdoc =
  :parents (numbers equal equality-variants acl2-built-ins)
  :short "Test equality of two numbers"
  :long "<p>@('(= x y)') is logically equivalent to @('(equal x y)').</p>

 <p>Unlike @(tsee equal), @('=') has a @(see guard) requiring both of its
 arguments to be numbers.  Generally, @('=') is executed more efficiently than
 @(tsee equal).</p>

 <p>For a discussion of the various ways to test against 0, See @(see
 zero-test-idioms).</p>

 <p>@('=') is a Common Lisp function.  See any Common Lisp documentation for
 more information.</p>

 @(def =)")

(defxdoc >
  :parents (numbers acl2-built-ins)
  :short "Greater-than test"
  :long "<p>@('>') is a macro, and @('(> x y)') expands to the same thing as
 @('(< y x)').  See @(see <).</p>

 <p>@('>') is a Common Lisp function.  See any Common Lisp documentation for
 more information.</p>

 @(def >)")

(defxdoc >=
  :parents (numbers acl2-built-ins)
  :short "Greater-than-or-equal test"
  :long "<p>@('>=') is a macro, and @('(>= x y)') expands to the same thing as
 @('(not (< x y))').  See @(see <).</p>

 <p>@('>=') is a Common Lisp function.  See any Common Lisp documentation for
 more information.</p>

 @(def >=)")

(defxdoc @
  :parents (programming-with-state acl2-built-ins)
  :short "Get the value of a global variable in @(tsee state)"
  :long "@({
  Examples:
  (+ (@ y) 1)
  (assign a (aset1 'ascii-map-array (@ a) 66 'Upper-case-B))

  General Form:
  (@ symbol)
 })

 <p>where @('symbol') is any symbol to which you have @(tsee assign)ed a global
 value.  This macro expands into @('(f-get-global 'symbol state)'), which
 retrieves the stored value of the symbol.</p>

 <p>The macro @('f-get-global') is closely related to @(tsee @): @('(@ var)')
 macroexpands to @('(f-get-global 'var state)').</p>

 <p>The macro @(tsee assign) makes it convenient to set the value of a symbol.
 The @(':')@(tsee ubt) operation has no effect on the @('global-table') of
 @(tsee 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.</p>")

(defxdoc |A Flying Tour of ACL2|
  :parents (|Pages Written Especially for the Tours|)
  :short "A Flying Tour of ACL2"
  :long "<p><see topic='@(url |About the ACL2 Home Page|)'><img
 src='res/tours/large-flying.gif'></img></see></p>

 <p>On this tour you will learn a little about what ACL2 is for rather than how
 ACL2 works.  At the top and bottom of the ``page'' there are ``flying tour''
 icons.  Click on either icon to go to the next page of the tour.</p>

 <p>The tour visits the following topics sequentially.  But on your first
 reading, don't navigate through the tour by clicking on these links; they are
 shown as live links only so that later you can determine what you've visited.
 Instead, just use the flying tour icons.</p>

 <code>
 <b>The Flight Plan</b>
 * <see topic='@(url |About the ACL2 Home Page|)'>This Documentation</see>
 * <see topic='@(url |What Is ACL2(Q)|)'>What is ACL2?</see>
 * <see topic='@(url |What is a Mathematical Logic(Q)|)'>Mathematical Logic</see>
 * <see topic='@(url |What is a Mechanical Theorem Prover(Q)|)'>Mechanical Theorem Proving</see>
 * <see topic='@(url |About Models|)'>Mathematical Models in General</see>
 * <see topic='@(url |Models of Computer Hardware and Software|)'>Mathematical Models of Computing Machines</see>
      <see topic='@(url |A Typical State|)'>Formalizing Models</see>
      <see topic='@(url |Running Models|)'>Running Models</see>
      <see topic='@(url |Symbolic Execution of Models|)'>Symbolic Execution of Models</see>
      <see topic='@(url |Proving Theorems about Models|)'>Proving Theorems about Models</see>
 * Requirements of ACL2
      <see topic='@(url |What is Required of the User(Q)|)'>The User's Skills</see>
      <see topic='@(url |How Long Does It Take to Become an Effective User(Q)|)'>Training</see>
      <see topic='@(url |Other Requirements|)'>Host System</see>
 </code>

 <p>On your first reading, don't explore other links you see in the tour.  Some
 of them lead to the Walking Tour, which you can take coherently when you
 finish this tour.  Others lead into the extensive hypertext documentation and
 you are liable to get lost there unless you're trying to answer a specific
 question.  We intend the tour to take about 10 minutes of your time.</p>

 <p><see topic='@(url |About the ACL2 Home Page|)'><img
 src='res/tours/flying.gif'></img></see></p>")

(defxdoc |A Sketch of How the Rewriter Works|
  :parents (|Pages Written Especially for the Tours|)
  :short "A Sketch of How the Rewriter Works"
  :long "<p>Below we show the first target term, extracted from the current
 conjecture.  Below it we show the associativity rule.</p>

 <p><img src='res/tours/uaa-rewrite.gif'></img></p>

 <p>The variables of the rewrite rule are <b>instantiated</b> so that the
 <b>left-hand side</b> of the rule matches the target:</p>

 @({
       variable          term from target
         a                     x1
         b                     x2
         c                     (app x3 x4)
 })

 <p>Then the target is <b>replaced</b> by the instantiated <b>right-hand
 side</b> of the rule.</p>

 <p>Sometimes rules have <b>hypotheses</b>.  To make a long story short, if the
 rule has hypotheses, then after matching the left-hand side, the rewriter
 instantiates the hypotheses and rewrites them recursively.  This is called
 <b>backchaining</b>.  If they all rewrite to true, then the target is replaced
 as above.</p>

 <p>We discuss the rewriter in more detail in the extended introduction to how
 to use the theorem prover, see @(see introduction-to-the-theorem-prover),
 which we will recommend you work through <b>after</b> you have finished the
 two tours.</p>")

(defxdoc |A Tiny Warning Sign|
  :parents (|Pages Written Especially for the Tours|)
  :short "A Tiny Warning Sign"
  :long "<p><img src='res/tours/warning.gif'></img></p>

 <p>This warning sign, which usually appears as ``<icon src='res/tours/twarning.gif'/>'',
 indicates that the link it marks takes you into ACL2's online
 documentation.</p>

 <p>The documentation is a vast graph of documented topics intended to help the
 <i>user</i> of ACL2 rather than the <i>potential user</i>.  If you are
 exploring ACL2's home page to learn about the system, perhaps you should go
 back rather than follow the link marked with this sign.  But you are welcome
 to explore the online documentation as well.  Good luck.</p>")

(defxdoc |A Trivial Proof|
  :parents (|Pages Written Especially for the Tours|)
  :short "A Trivial Proof"
  :long "<p><img src='res/tours/concrete-proof.gif'></img></p>")

(defxdoc |A Typical State|
  :parents (|Pages Written Especially for the Tours|)
  :short "A Typical State"
  :long "<p><see topic='@(url |Functions for Manipulating these Objects|)'><img
 src='res/tours/flying.gif'></img></see></p>

 <p><img src='res/tours/state-object.gif'></img></p>

 <p>Observe that the states in typical models talk about</p>

 <code>
 <b>booleans</b>    <b>integers</b>   <b>vectors</b>     <b>records</b>   <b>caches</b>
 <b>bits</b>        <b>symbols</b>    <b>arrays</b>      <b>stacks</b>    <b>files</b>
 <b>characters</b>  <b>strings</b>    <b>sequences</b>   <b>tables</b>    <b>directories</b>
 </code>

 <p>These objects are <b>discrete</b> rather than <b>continuous</b>;
 furthermore they are built incrementally or <b>inductively</b> by repeatedly
 using primitive operations to put together smaller pieces.</p>

 <p>The functions we need to manipulate these objects do things like
 <b>concatenate</b>, <b>reverse</b>, <b>sort</b>, <b>search</b>, <b>count</b>,
 etc.</p>

 <p><see topic='@(url |Functions for Manipulating these Objects|)'><img
 src='res/tours/flying.gif'></img></see></p>")

(defxdoc |A Walking Tour of ACL2|
  :parents (|Pages Written Especially for the Tours|)
  :short "A Walking Tour of ACL2"
  :long "<p><see topic='@(url |Common Lisp|)'><img
 src='res/tours/large-walking.gif'></img></see></p>

 <p>On this tour you will learn a little more about the ACL2 logic, the theorem
 prover, and the user interface.</p>

 <p>This time we will stick with really simple things, such as the
 associativity of list concatenation.</p>

 <p>We assume you have taken the Flying Tour but that you did not necessarily
 follow all the ``off-tour'' links because we encouraged you not to.  With the
 Walking Tour we encourage you to visit off-tour links &mdash; provided they
 are not marked with the tiny warning sign (<see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>).
 But they are ``branches'' in the tour that lead to ``dead ends.''  When you
 reach a dead end, remember to use your browser's Back Button to return to the
 Walking Tour to continue.</p>

 <p>When you get to the end of the tour we'll give you a chance to repeat
 quickly both the Flying and the Walking Tours to visit any off-tour links
 still of interest.</p>

 <p><see topic='@(url |Common Lisp|)'><img src='res/tours/walking.gif'></img></see></p>")

(defxdoc a!
  :parents (ld)
  :short "To return to the top-level of ACL2's command loop"
  :long "<p>When @('(a!)') is evaluated inside of ACL2's command loop, the
 current computation is aborted and control returns to the top of the command
 loop, exactly as though the user had interrupted and aborted the current
 computation.  (Note: Versions of ACL2 up to Version_3.4 provided `@('#.')' for
 this purpose, but no longer; see @(see sharp-dot-reader).)</p>

 <p>If you are at an ACL2 prompt (as opposed to a raw Lisp break), then you may
 type @(':a!') in place of @('(a!)'); see @(see keyword-commands).</p>

 <p>For a related feature that only pops up one level of @(tsee ld), see @(tsee
 p!).  However, @('p!') behaves differently if you're typing to the interactive
 break caused by @(see break-rewrite).  Instead of popping up one level,
 @('p!') in break-rewrite prints a message and is otherwise a no-op.</p>

 <p>Logically speaking, @('(a!) = nil').  But imagine that it is defined in
 such a way that it causes a stack overflow or other resource exhaustion when
 called.</p>")

(defxdoc abort!
  :parents (ld)
  :short "To return to the top-level of ACL2's command loop"
  :long "<p>This is an alias for @('a!'); see @(see a!).  For a related feature
 that only pops up one level, see @(see p!).</p>")

(defxdoc abort-soft
  :parents (miscellaneous)
  :short "Control how interrupts are handled in proofs"
  :long "<p>ACL2 arranges by default that when a proof is interrupted (with
 @('Control-C')), a ``soft'' abort occurs in the following sense: the message
 below is printed and then the proof attempt continues temporarily before
 ultimately failing (usually very soon thereafter).</p>

 @({
 ***********************************************
 Note:  interrupt signal
   Will attempt to exit the proof in progress;
   otherwise, the next interrupt will abort the proof.
   For an immediate abort see :DOC abort-soft.
 ***********************************************
 })

 <p>This default behavior supports proper operation of the utility, @(tsee
 redo-flat), when a proof is interrupted.  It also supports more complete
 summaries than would be obtained with an immediate abort.  If you nevertheless
 want proofs to abort immediately, you may evaluate the form @('(assign
 abort-soft nil)').  To restore the default behavior, evaluate @('(assign
 abort-soft t)').</p>

 <p>Remarks for system hackers.</p>

 <ul>

 <li>An important effect of having evaluated @('(assign abort-soft nil)') is
 that an interrupt will send you immediately back to the ACL2 read-eval-print
 loop, in contrast to the default behavior where the prover returns an @(see
 error-triple) whose error component is non-@('nil').</li>

 <li>It may be preferable to bind @(see state) global @('abort-soft') rather
 than to assign it globally.  See the implementation of @(see
 prove$) (specifically, the definition of @('prove$-fn') in @(see
 community-book) @('books/tools/prove-dollar.lisp')) for an example.</li>

 </ul>")

(defxdoc about-acl2
  :parents (start-here)
  :short "General information About ACL2"
  :long "<p>This is @(`(:raw (@ acl2-version))`), @(see copyright) (C) 2026,
 Regents of the University of Texas, authored by Matt Kaufmann and J Strother
 Moore.</p>

 <p>This manual contains <see topic='@(url installation)'>installation
 instructions</see>, <see topic='@(url acl2-tutorial)'>tutorials</see>, and
 @(see acknowledgments), as well as information about <see topic='@(url
 mailing-lists)'>mailing lists</see>, related @(see publications), and <see
 topic='@(url workshops)'>ACL2 Workshops</see>.</p>

 <p>See @(see documentation) for how to access the ACL2+Books User's Manual.
 See @(see releases) for information about past ACL2 releases.  See the <a
 href='http://www.cs.utexas.edu/users/moore/acl2/'>ACL2 home page</a> for other
 information, including seminars.</p>

 <p>For statistics on ACL2 code size, see file @('doc/acl2-code-size.txt').</p>")

(defxdoc abs
  :parents (numbers acl2-built-ins)
  :short "The absolute value of a real number"
  :long "<p>@('(Abs x)') is @('-x') if @('x') is negative and is @('x')
 otherwise.</p>

 <p>The @(see guard) for @('abs') requires its argument to be a rational (@(see
 real), in ACL2(r)) number.</p>

 <p>@('Abs') is a Common Lisp function.  See any Common Lisp documentation for
 more information.</p>

 <p>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.</p>

 @(def abs)")

(defxdoc access
  :parents (defrec acl2-built-ins)
  :short "Accessor macro for @(see defrec) structures."
  :long "<p>The @('access') macro is built into ACL2, and allows you to access
 particular fields from structures that have been introduced with @(see
 defrec).  For instance:</p>

 @({
    (access employee x :name)
 })

 <p>would return the @('name') field from the employee @('x').  See @(see
 defrec) for more information.</p>")

(defxdoc accumulated-persistence
  :parents (debugging)
  :short "To get statistics on which @(see rune)s are being tried"
  :long "@({
  Useful Forms:
  (accumulated-persistence t)              ; Activate statistics gathering.
  (accumulated-persistence :all)           ; As above, ``enhanced'' (see below)

  (show-accumulated-persistence :frames)   ; Display statistics ordered by
  (show-accumulated-persistence :tries)    ; frames built, times tried,
  (show-accumulated-persistence :ratio)    ; or their ratio.
  (show-accumulated-persistence)           ; Same as supplying :frames argument.

  (accumulated-persistence nil)            ; Deactivate.

  (accumulated-persistence-oops)           ; Undo the clearing effect of
                                           ; (accumulated-persistence t).

  Advanced forms:
  (show-accumulated-persistence :frames-s) ; The `s', `f', and `a' suffixes
  (show-accumulated-persistence :frames-f) ; stand for `success' (`useful'),
  (show-accumulated-persistence :frames-a) ; `failure' (`useless'), and `all',
  (show-accumulated-persistence :tries-s)  ; respectively.  The only effect of
  (show-accumulated-persistence :tries-f)  ; the `s' and `f' versions is to
  (show-accumulated-persistence :tries-a)  ; sort first by useful or useless
                                           ; applications, respectively (see
                                           ; below).  The `a' versions avoid
                                           ; showing the useful/useless
                                           ; breakdown.

  (show-accumulated-persistence :runes)    ; Just show runes alphabetically.
  (show-accumulated-persistence :useless)  ; Just show useless runes.
  (show-accumulated-persistence :useless :list)
                                           ; Just show useless runes as a list.
 })

 <p>In summary, @('(accumulated-persistence t)') turns on fresh statistics
 gathering for rules, @('(accumulated-persistence nil)') turns it off,
 @('(show-accumulated-persistence)') displays the statistics that were
 gathered, and @('(accumulated-persistence-oops)') restores the statistics, if
 any, that were cleared by @('(accumulated-persistence t)') or
 @('(accumulated-persistence :all)').</p>

 <p>In general, if the optional second argument of
 @('show-accumulated-persistence') is supplied as @(':list'), then instead of
 the result being displayed a ``pretty'' human-readable format, the result will
 be displayed as a corresponding list of entries of the form @('(frames tries
 xrune)').</p>

 <p>Note: @('set-accumulated-persistence') is equivalent to
 @('accumulated-persistence').</p>

 <p>See the end of this item for a discussion of ``enhanced statistics
 gathering,'' which can be useful for more fine-grained proof debugging.</p>

 <p>Generally speaking, the more ACL2 knows, the slower it runs.  That is
 because the search space grows with the number of alternative rules.  Often,
 the system tries to apply rules that you have forgotten were even there, if
 you knew about them in the first place!  ``Accumulated-persistence'' is a
 statistic (originally developed for Nqthm) that helps you identify the rules
 that are causing ACL2's search space to explode.</p>

 <p>For other proof debugging utilities, see @(see break-rewrite), @(see
 with-brr-data), and @(see dmr).</p>

 <p>Accumulated persistence tracking can be turned on or off.  It is generally
 off.  When on, proofs may take a little more time than otherwise.  (We
 measured approximately 11% more time in a so-called ``everything'' regression
 run in May 2020.)  But some useful numbers are collected.  When it is turned
 on, by</p>

 @({
  ACL2 !>(accumulated-persistence t)
 })

 <p>an accumulation site is initialized and henceforth data about which rules
 are being tried is accumulated into that site.  That accumulated data can be
 displayed with @('show-accumulated-persistence'), as described in detail
 below.  When accumulated persistence is turned off, with
 @('(accumulated-persistence nil)'), the accumulation site is wiped out and the
 data in it is lost.</p>

 <p>The ``accumulated persistence'' of a @(see rune) is the number of @(see
 rune)s the system has attempted to apply (since accumulated persistence was
 last activated) while the given @(see rune) was being tried.</p>

 <p>Consider a @(':')@(tsee rewrite) rule named @(tsee rune).  For simplicity,
 let us imagine that @(tsee rune) is tried only once in the period during which
 accumulated persistence is being monitored.  Recall that to apply a rewrite
 rule we must match the left-hand side of the conclusion to some term we are
 trying to rewrite, establish the hypotheses of @(tsee rune) by rewriting, and,
 if successful, then rewrite the right-hand side of the conclusion.  We say
 @(tsee rune) is ``being tried'' from the time we have matched its left-hand
 side to the time we have either abandoned the attempt or finished rewriting
 its right-hand side.  (By ``match'' we mean to include any loop-stopper
 requirement; see @(see loop-stopper).)  During that period of time other rules
 might be tried, e.g., to establish the hypotheses.  The rules tried while
 @(tsee rune) is being tried are ``billed'' to @(tsee rune) in the sense that
 they are being considered here only because of the demands of @(tsee rune).
 Thus, if no other rules are tried during that period, the accumulated
 persistence of @(tsee rune) is @('1') &mdash; we ``bill'' @(tsee rune) once
 for its own application attempt.  If, on the other hand, we tried @('10')
 rules on behalf of that application of @(tsee rune), then @(tsee rune)'s
 accumulated persistence would be @('11').</p>

 <p>One way to envision accumulated persistence is to imagine that every time a
 @(see rune) is tried it is pushed onto a stack.  The rules tried on behalf of
 a given application of a @(see rune) are thus pushed and popped on the stack
 above that @(see rune).  A lot of work might be done on its behalf &mdash; the
 stack above the @(see rune) grows and shrinks repeatedly as the search
 continues for a way to use the @(see rune).  All the while, the @(see rune)
 itself ``persists'' in the stack, until we finish with the attempt to apply
 it, at which time we pop it off.  The accumulated persistence of a @(see rune)
 application is thus the number of stack frames built while that @(see rune)
 was on the stack.</p>

 <p>Note that accumulated persistence is tallied whether or not the attempt to
 apply a @(see rune) is successful.  Each of the rules tried on its behalf
 might have failed and the attempt to apply the @(see rune) might have also
 failed.  The ACL2 proof script would make no mention of the @(see rune) or the
 rules tried on its behalf because they did not contribute to the proof.  But
 time was spent pursuing the possible application of the @(see rune) and
 accumulated persistence is a measure of that time.</p>

 <p>A high accumulated persistence might come about in two extreme ways.  One
 is that the rule causes a great deal of work every time it is tried.  The
 other is that the rule is ``cheap'' but is tried very often.  We therefore
 keep track of the number of times each rule is tried as well as its
 persistence.  The ratio between the two is the average amount of work done on
 behalf of the rule each time it is tried.</p>

 <p>We do not claim that tracking of runes for accumulated-persistence is
 perfect.  In practice, we believe it is quite reliable with the exception of
 @(see congruence) runes and, in some cases @(see executable-counterpart)
 runes. (For the latter, details are in a comment in the ACL2 source definition
 of function @('print-useless-runes').)</p>

 <p>When the accumulated persistence totals are displayed by the function
 @('show-accumulated-persistence') we sort them so that the most expensive
 @(see rune)s are shown first.  We can sort according to one of three basic
 keys:</p>

 @({
  :frames - the number of frames built on behalf of the rune
  :tries  - the number of times the rune was tried
  :ratio  - frames built per try
 })

 <p>The key simply determines the order in which the information is presented.
 If no argument is supplied to @('show-accumulated-persistence'), @(':frames')
 is used.</p>

 <p>The display breaks each total into ``useful'' and ``useless'' subtotals.  A
 ``useful'' rule try is one that is viewed as contributing to the progress of
 the proof, and the rest are ``useless'' rule applications.  For example, if a
 @(':')@(tsee rewrite) rule is tried but its hypotheses are not successfully
 relieved, then that rule application and all work done on behalf of those
 hypotheses is ``useless'' work.  In general, an attempt to apply a @(see rune)
 is viewed as ``useful'' unless the attempt fails or the attempt is on the
 stack (as described above) for a @(see rune) application that ultimately
 fails.  A large number of ``useless'' @(':frames') or @(':tries') along with
 correspondingly small ``useful'' counts may suggest @(see rune)s to consider
 disabling (see @(see disable) and see @(see in-theory)).  Thus, here is a more
 complete list of the arguments that may be supplied to
 @('show-accumulated-persistence').  Suffixes ``s'', ``f'', and ``a'' are
 intended to suggest ``success'' (``useful''), ``failure'' (``useless''), and
 ``all''.</p>

 @({
  :frames     - sort by the number of frames built on behalf of the rune
     :frames-s -   as above, but sort by useful applications
     :frames-f -   as above, but sort by useless applications
     :frames-a -   as above, but inhibit display of ``useful'' and
                   ``useless'' subtotals
  :tries      - sort by the number of times the rune was tried
     :tries-s  -   as above, but sort by useful applications
     :tries-f  -   as above, but sort by useless applications
     :tries-a  -   as above, but inhibit display of ``useful'' and
                   ``useless'' subtotals
  :ratio      - sort by frames built per try
  :useless    - show only the runes tried whose tries were all ``useless''
 })

 <p>For a given line of the report, every frame credited to a ``useful''
 (respectively, ``useless'') rule application is considered ``useful''
 (respectively, ``useless'').  We illustrate with the following example.</p>

 @({
  (progn
    (defstub hyp (x) t)
    (defstub concl (x) t)
    (defstub bad (x) t)
    (defstub good (x) t)
    (defaxiom good-ax
      (implies (good x) (hyp x)))
    (defaxiom bad-ax
      (implies (bad x) (hyp x)))
    (defaxiom hyp-implies-concl
      (implies (hyp x) (concl x)))
    )
  (accumulated-persistence t)
  (thm (implies (good x) (concl x)))
  (show-accumulated-persistence)
 })

 <p>To prove the @(tsee thm) form, ACL2 attempts to rewrite @('(concl x)') to
 true by applying rule @('hyp-implies-concl').  It then attempts to establish
 @('(hyp x)') first by trying rule @('bad-ax'), which fails, and second by
 trying rule @('good-ax'), which succeeds.  As expected, the report labels as
 ``useless'' the failure of the attempt to establish the hypothesis, @('(bad
 x)').</p>

 @({
     --------------------------------
           1        1 (    1.00) (:REWRITE BAD-AX)
           0        0    [useful]
           1        1    [useless]
     --------------------------------
 })

 <p>Now consider the top-level application of rule @('hyp-implies-concl').
 Even though the above report shows the application of @('bad-ax') as
 ``useless'', note that this rule was applied on behalf of the successful
 (``useful'') application of @('hyp-implies-concl'), and hence is incorporated
 into the ``useful'' line for @('hyp-implies-concl'), as follows.</p>

 @({
     --------------------------------
           3        1 (    3.00) (:REWRITE HYP-IMPLIES-CONCL)
           3        1    [useful]
           0        0    [useless]
     --------------------------------
 })

 <p>In summary: categorization of @(':frames') as ``useful'' or ``useless'' is
 based on whether they support ``useful'' or ``useless'' @(':tries').</p>

 <p>See @(see useless-runes) for a way to speed up proofs by automatically
 turning off useless rules.</p>

 <p>Note that a @(see rune) with high accumulated persistence may not actually
 be the ``culprit.''  For example, suppose @('rune1') is reported to have a
 @(':ratio') of @('101'), meaning that on the average a hundred and one frames
 were built each time @('rune1') was tried.  Suppose @('rune2') has a
 @(':ratio') of @('100').  It could be that the attempt to apply @('rune1')
 resulted in the attempted application of @('rune2') and no other @(see rune).
 Thus, in some sense, @('rune1') is ``cheap'' and @('rune2') is the ``culprit''
 even though it is reported as costing less than @('rune1').</p>

 <p>If a proof is aborted, then in general, @(tsee
 show-accumulated-persistence) will only display totals for runes whose
 attempted application is complete: that is, if the rewriter was in the process
 of relieving hypotheses for a rule, then information for that rule will not be
 included in the tally.  We say ``in general'' because, as indicated near the
 top of the output from @(tsee show-accumulated-persistence) when such
 incomplete information is omitted, you can get this information by using
 argument @(':frames-a') or @(':tries-a').</p>

 <p>There are other subtleties in how rune applications are tallied, documented
 elsewhere: see @(see accumulated-persistence-subtleties).</p>

 <p>We conclude with a discussion of ``enhanced'' statistics gathering, which
 is enabled by supplying @('accumulated-persistence') the argument
 @(':ALL'):</p>

 @({
  (accumulated-persistence :all)
 })

 <p>At some additional performance expense (but probably well under a factor of
 2 altogether), ACL2 then gathers additional statistics for individual
 hypotheses of rules as well as their conclusions.  To understand how this
 works, suppose @('rn') is a @(see rune).  Then we prepend the keyword
 @(':CONC') to @('rn') to form what we call its ``conclusion xrune'', and for
 its @('I')-th hypothesis we prepend @(':HYP I') to @('rn') to form its
 @('I')-th ``hypothesis xrune.''  Here, ``xrune'' is pronounced ``ex rune'',
 and is mnemonic for ``extended rune.''  For example, if @('(REWRITE FOO)') is
 a @(see rune) then @('(:CONC REWRITE FOO)') is its conclusion xrune, and
 @('(:HYP 2 REWRITE FOO)') is a hypothesis xrune corresponding to the second
 hypothesis of the corresponding rewrite rule.</p>

 <p>With @('(accumulated-persistence :all)'), we instruct ACL2 to track not
 only runes but also xrunes.  Then, @('(show-accumulated-persistence)') will
 display information for all xrunes in a format that we consider to be ``raw'',
 in the sense that data for xrunes are displayed just as for runes.  But a
 ``merged'' format is also available.  Here is a summary of display commands,
 followed below by further discussion.</p>

 @({
    (show-accumulated-persistence :frames t) ; t is optional, i.e., the default
       ; Display enhanced statistics sorted by frames, in a ``raw'' format.
    (show-accumulated-persistence :frames :merge)
       ; Display enhanced statistics sorted by frames, in a ``merged'' format.
    (show-accumulated-persistence :frames nil)
       ; Display regular statistics sorted by frames
       ; (runes only, that is, without the enhancements).
    (show-accumulated-persistence :frames :merge)
       ; Display a list of entries (frames tries xrune), sorted by frames

    ; More generally, the descriptions just above apply for any legal first
    ; argument:

    (show-accumulated-persistence KEY t)
    (show-accumulated-persistence KEY :merge)
    (show-accumulated-persistence KEY nil)
    (show-accumulated-persistence KEY :list)

    ; Note also these alternate forms, equivalent to the first of the two forms
    ; just above, i.e., the form with second argument of t:
    (show-accumulated-persistence KEY :raw)
    (show-accumulated-persistence KEY)
 })

 <p>There is a significant difference between how runes are tracked and how
 ACL2 tracks hypothesis and conclusion xrunes: unlike regular runes, these
 xrunes do not contribute to the accumulated @(':frames') counts.  Rather, they
 serve as accumulation sites without contributing their @(':tries') to any
 accumulation.  Consider for example the snippet below, taken from a report
 created with the @(':merge') option (to be discussed further below), i.e., by
 evaluating the form @('(show-accumulated-persistence :frames :merge)').</p>

 @({
     :frames   :tries    :ratio  rune
     --------------------------------
         462      211 (    2.18) (:REWRITE PERM-MEM)
          13        6    [useful]
         449      205    [useless]
        .............................
         251       47 (    5.34) (:HYP 2 :REWRITE PERM-MEM)
           6        6    [useful]
         245       41    [useless]
        .............................
           0      211 (    0.00) (:HYP 1 :REWRITE PERM-MEM)
           0        6    [useful]
           0      205    [useless]
        .............................
           0        7 (    0.00) (:CONC :REWRITE PERM-MEM)
           0        6    [useful]
           0        1    [useless]
     --------------------------------
 })

 <p>Notice that while @(':tries') are recorded for the xrune @('(:HYP 1
 :REWRITE PERM-MEM)'), no @(':frames') are recorded.  This is because no stack
 frames were built for runes while this xrune was on the stack &mdash; only for
 the xrune itself, which as we explained above is not accumulated into the
 total @(':frames') counts.  As it turns out, this lack of stack frames is
 explained by the fact that the rewrite rule @('PERM-MEM') has a free variable
 in the first hypothesis.</p>

 @({
  ACL2 !>:pe perm-mem
           18  (DEFTHM PERM-MEM
                       (IMPLIES (AND (PERM X Y) (MEM A X))
                                (MEM A Y))
                       :RULE-CLASSES ((:REWRITE :MATCH-FREE :ONCE)))
  ACL2 !>
 })

 <p>The second hypothesis, however, does cause additional rewriting in order to
 rewrite it to true, resulting in 251 stack frames for runes.  We see that the
 conclusion does not lead to creation of any rune stack frames, which might
 seem to suggest that only 251 stack frames for runes were created on behalf of
 this rule application &mdash; yet, we see that 462 frames were actually
 created.  The difference is the 211 frames created for the rewrite rule
 itself.  Even if the total had been a bit more than 462, one need not be
 surprised, as there could be some work recorded during application of the
 rewrite rule, such as <see topic='@(url type-reasoning)'>type reasoning</see>,
 that is not done during rewriting of a hypothesis or the conclusion.</p>

 <p>Now suppose we have executed @('(accumulated-persistence :all)') and
 attempted some proofs, and now we are ready to see statistics.  The form
 @('(show-accumulated-persistence)') displays statistics exactly as described
 above, treating these extra xrunes just as though they are runes; similarly
 for the form @('(show-accumulated-persistence KEY)'), for any legal @('KEY').
 A second optional argument may however be supplied to
 @('show-accumulated-persistence').  The default for that second argument is
 @('t'), and a second argument of @(':raw') is treated the same as @('t');
 thus, these arguments provide the behavior just described, where data for
 xrunes are displayed just as for runes.  You may restrict output to runes,
 ignoring hypothesis and conclusion xrunes, by giving a second argument of
 @('nil').  (This gives the same behavior as if we had started with the command
 @('(accumulated-persistence t)') instead of the command
 @('(accumulated-persistence :all)').)  You may give a second argument
 of @(':merge'), in which case output will be sorted and displayed as though
 only runes were tracked (not the extra xrunes), but each data item for a
 non-rune xrune will be merged so that it is displayed in suitable order just
 below its corresponding rune, as in the @('PERM-MEM') example displayed
 above.  Finally, you may give a second argument of @(':list'), which is
 equivalent to the default second argument of @('t'), except that the results
 are printed as a list of entries @('(frames tries xrune)').</p>

 <p>We close by mentioning two aspects of enhanced statistics display for
 @(':CONC') xrunes that have potential to be confusing.  First consider the
 following example.</p>

 @({
       :frames   :tries    :ratio  rune
     --------------------------------
          14        4 (    3.50) (:REWRITE DEFAULT-+-2)
           0        0    [useful]
          14        4    [useless]
        .............................
          10        4 (    2.50) (:HYP 1 :REWRITE DEFAULT-+-2)
           0        0    [useful]
          10        4    [useless]
     --------------------------------
 })

 <p>It may be surprising that no data is displayed for the corresponding
 @(':CONC') xrune.  The explanation, however, is simple: the hypothesis never
 rewrote to true, so the conclusion was never rewritten.  This is consistent
 with the marking as ``useless'' of all @(':frames') and @(':tries') for the
 rune and the hypothesis xrune.  Note by the way, once again, that the
 hypothesis xrune does not contribute to any @(':frames') count.</p>

 <p>Another reason not to see data displayed for a @(':CONC') xrune is that if
 a rule has no hypotheses, then no such data is collected.  This decision was
 made because in the case of no hypotheses, we expect it to be very rare that
 information for the @(':CONC') xrune will add any useful insight.</p>

 <p>On a final note: @('(show-accumulated-persistence :runes)') may be used
 simply to see a list of all @(see rune)s (or xrunes) displayed
 alphabetically.</p>

 <p>Users are encouraged to think about other meters we could install in ACL2
 to help diagnose performance problems.</p>")

(defxdoc accumulated-persistence-subtleties
  :parents (accumulated-persistence)
  :short "Some subtle aspects of the counting done by @(tsee accumulated-persistence)"
  :long "<p>In this topic we cover the overcounting of ``useful'' @(see rune)
 application attempts, and we describe how ``useless'' rune application
 attempts can actually be critical for a proof's success.  We conclude with a
 few words about counting frames when there are nested (recursive) applications
 of a rune.</p>

 <p><i>Overcounting of ``useful'' rune application attempts.</i> Not every
 @(see rune) application may be necessary for a proof's success.  Consider for
 example:</p>

 @({
  (thm (equal (car (cons a (cdr (cons b x))))
              a))
 })

 <p>Then @('show-accumulated-persistence') will tell us that @(':')@(tsee
 rewrite) rules @('car-cons') and @('cdr-cons') each had one useful
 application.  However, the rule @('cdr-cons') is used to simplify @('(cdr
 (cons b x))') to @('x'), and this simplification is unnecessary for the proof.
 Indeed, the proof succeeds even when preceded by the event: @('(in-theory
 (disable cdr-cons))').  We thus see that a @(see rune) application labeled as
 ``useful'' may be simplifying a term that is not relevant to the proof.</p>

 <p>As of this writing, we consider every @(':')@(tsee forward-chaining) rule
 application to be ``useful'', for simplicity of the implementation.  Moreover,
 our counting of these rules is such that a single rule may be counted more
 than once.</p>

 <p><i>How ``useless'' attempts can be critical for a proof's success.</i> The
 command @('(accumulated-persistence :useless')) will list rules that did not
 contribute directly to the proof (see @(see accumulated-persistence), in
 particular the discussion of ``useless'' there).  However, a ``useless'' rule
 can on rare occasions be critical to the success of a proof.  In the following
 example, we have a ``bad'' rule that can take the proof in the wrong
 direction, but a ``useless'' rule does a rewrite that prevents the successful
 relieving of a hypothesis of the ``bad'' rule.  In summary:</p>

 @({
  ; Assume p0.  We want to prove p1.

  ; Key rule:
  p0 -> p1 = t

  ; Bad rule that could ruin the proof:
  p3 -> p1 = p2

  ; But unfortunately, we know p3:
  p0 -> p3

  ; Important ``useless'' rule, preventing ``bad rule'' above from firing:
  p3 = p4
 })

 <p>The following event captures the rules described above.</p>

 @({
  (encapsulate
   ((p0 (x) t)
    (p1 (x) t)
    (p2 (x) t)
    (p3 (x) t)
    (p4 (x) t))
   (local (defun p0 (x) x))
   (local (defun p1 (x) x))
   (local (defun p2 (x) x))
   (local (defun p3 (x) x))
   (local (defun p4 (x) x))

  ; Key rule:
   (defthm p0-implies-p1
     (implies (p0 x)
              (p1 x)))

  ; Bad rule that could ruin the proof:
   (defthm p3-implies-p1-is-p2
     (implies (p3 x)
              (equal (p1 x) (p2 x))))

  ; But unfortunately, we know p3:
   (defthm p0-implies-p3
     (implies (p0 x)
              (p3 x)))

  ; Important ``useless'' rule, preventing p3-implies-p1-is-p2 from firing:
   (defthm p3-is-p4
     (equal (p3 x) (p4 x))))
 })

 <p>Now we can see that @('p3-is-p4') is labeled as ``useless'', by evaluating
 these commands.</p>

 @({
  (accumulated-persistence t)
  (thm (implies (p0 x) (p1 x)))
  (show-accumulated-persistence)
 })

 <p>If instead we first evaluate @('(in-theory (disable p3-is-p4))') before the
 @('thm') above, then the proof fails, even though @('p3-is-p4') was labeled as
 ``useless''!</p>

 <p>Nevertheless, in general it is probably safe to disable rules reported as
 ``useless'' by @('(show-accumulated-persistence :useless)'), and doing so may
 speed up a proof considerably.</p>

 <p>Remark. The example above suggests a surprising fact: on rare occasions, a
 proof may fail when you give an @(':')@(tsee in-theory) hint consisting of
 exactly the @(see rune)s reported in a proof that succeeds.  For, imagine a
 rule R that is needed in part of the proof but is ``bad'' in a second part,
 and that some other, ``useless'' rule prevents the application of R in that
 second part.  The example above suggests that disabling this ``useless'' rule
 can allow the second application of R, thus preventing the proof.</p>

 <p>Finally we discuss accumulation into frame counts in the case of a nested
 (recursive) application of a rule: that is, the case that during the
 application of a rule, the rule is applied again &mdash; in particular, while
 relieving a hypothesis or rewriting the right-hand side from the original rule
 application.  Recall that the implementation of @(see accumulated-persistence)
 keeps a stack of @(see rune)s currently being applied; thus, we are
 considering here the case that a rune is pushed onto a stack on which it
 already resides.  In that case, we count tries as usual but we avoid
 accumulating until we reach the outermost (topmost) application of that rune.

 Consider the following example.</p>

 @({
  (defun mem (a x)
    (if (atom x)
        nil
      (or (equal a (car x)) (mem a (cdr x)))))
 })

 <p>Now suppose we consider the theorem @('(mem a (list 1 2 3 a))').  Each time
 the definition of @('mem') is applied, a new stack frame is pushed.  We avoid
 accumulating into the @(':frames') count for that stack frame unless it is the
 topmost stack frame for that definition.  Otherwise the final @(':frames')
 count would be the sum of the counts for those individual frames, which form a
 linear sequence whose sum would therefore be quadratic in the number of
 applications of the definition of @('mem').</p>")

(defxdoc acknowledgments
  :parents (about-acl2)
  :short "Some contributors to the well-being of ACL2"
  :long "<p>The development of ACL2 was initially made possible by funding from
 the U. S. Department of Defense, including ARPA and ONR.  We thank all the
 organizations that have contributed support, including the following (in
 alphabetical order).</p>

 <ul>

 <li>AMD, for providing significant time over several years for Matt Kaufmann
 to carry out ACL2 research, support, and development</li>

 <li>Computational Logic, Inc. and its president, Don Good, where the first
 eight years of ACL2 development occurred</li>

 <li>Centaur Technology</li>

 <li>Collins Aerospace</li>

 <li>DARPA</li>

 <li>Digital Equipment Corporation</li>

 <li>EDS, which provided some time for Matt Kaufmann's ACL2 work 1998-1999</li>

 <li>ForrestHunt and, more generally, Warren A. Hunt, Jr. (see below)</li>

 <li>IBM</li>

 <li>Intel</li>

 <li>Kestrel Institute</li>

 <li>Kestrel Technology</li>

 <li>NSF (see below)</li>

 <li>ONR</li>

 <li>SRC</li>

 <li>Sun Microsystems</li>

 <li>U.S. Army, in particular ARL</li>

 <li>University of Texas at Austin (in particular support to J Moore through the
 Admiral B. R.  Inman Chair of Computing Theory)</li>

 </ul>

 <p>Regarding DARPA support: We thank DARPA for approving release of the
 following documentation topics and support with &ldquo;DISTRIBUTION
 STATEMENT A. Approved for public release. Distribution is
 unlimited.&rdquo;</p>

 <ul>

  <li>@(see Recursion-and-induction) together with its subtopics and its answer
      key (@(see community-books) files @('demos/r-and-i-answer-key-input.lsp')
      and @('demos/r-and-i-answer-key-log.txt'))</li>

  <li>@(see Gentle-introduction-to-ACL2-programming)</li>

  <li>@(see Loop$-primer) together with its subtopics and its answer key
      (@(see community-books) files @('lp6.lisp'), @('lp8.lisp'),
      @('lp12.lisp'), @('lp14.lisp'), @('lp17-11-lemma2.lisp'), and
      @('lp17.lisp'))</li>

  <li>@(see Start-here)</li>

 </ul>

 <p>Regarding NSF support:</p>

 <ul>

  <li>This material is based upon work supported by the National Science
      Foundation under Grant Nos. CCF-1526760, CNS-1525472, CCF-1153558,
      EIA-0303609, CNS-0429591, ISS-0417413, CCF-0945316, and CNS-0910913.</li>

  <li>Any opinions, findings and conclusions or recommendations expressed in
      this material are those of the authors and do not necessarily reflect the
      views of the National Science Foundation.</li>

 </ul>

 <p>We are especially grateful to Warren A. Hunt, Jr. for his unrivaled efforts
 in securing support for the entire ACL2 research group at both Computational
 Logic, Inc., and the University of Texas at Austin.  Without his efforts, we
 would have spent less time working on the system and fewer students would have
 been funded to apply it.</p>

 <p>ACL2 was started in August, 1989 by Boyer and Moore working together.  They
 co-authored the first versions of axioms.lisp and basis.lisp, with Boyer
 taking the lead in the formalization of ``@(see state)'' and the most
 primitive @(see io) functions.  Boyer also had a significant hand in the
 development of the early versions of the files interface-raw.lisp and
 translate.lisp.  For several years, Moore alone was responsible for developing
 the ACL2 system code, though he consulted often with both Boyer and Kaufmann.
 In August, 1993, Kaufmann became jointly responsible with Moore for developing
 the system.  Boyer has continued to provide valuable consulting on an informal
 basis.</p>

 <p>Bishop Brock was the heaviest early user of ACL2, and provided many
 suggestions for improvements.  In particular, the @(':cases') and
 @(':restrict') @(see hints) were his idea; he developed an early version of
 congruence-based reasoning for Nqthm; and he helped in the development of some
 early @(see books) about arithmetic.  In a demonstration of his courage and
 faith in us, he pushed for Computational Logic, Inc., to agree to the Motorola
 CAP contract &mdash; which required formalizing a commercial DSP in the
 untested ACL2 &mdash; and moved to Scottsdale, AZ, to do the work with the
 Motorola design team.  His demonstration of ACL2's utility was an inspiration,
 even to those of us designing ACL2.</p>

 <p>John Cowles also helped in the development of some early @(see books) about
 arithmetic, and also provided valuable feedback and bug reports.</p>

 <p>Other early users of ACL2 at Computational Logic, Inc. helped influence its
 development.  In particular, Warren Hunt helped with the port to Macintosh
 Common Lisp, and Art Flatau and Mike Smith provided useful general
 feedback.</p>

 <p>Mike Smith helped develop the Emacs portion of the implementation of proof
 trees.</p>

 <p>ACL2 depends on the availability of robust Common Lisp implementations, so
 we are grateful to the developers of those implementations.  Early in ACL2's
 history, Bill Schelter made some enhancements to AKCL (now GCL) that helped to
 enhance ACL2 performance in that Common Lisp implementation, and more
 generally, responded helpfully to our bug reports.  Camm Maguire has since
 provided wonderful GCL support, and has created a Debian package for ACL2
 built on GCL.  Gary Byers and R. Matthew Emerson have continually improved
 Clozure Common Lisp (CCL), often based on feedback from the ACL2 community.
 We are also grateful to developers of other Common Lisp implementations.</p>

 <p>Kent Pitman helped in our interaction with the ANSI Common Lisp
 standardization committee, X3J13.</p>

 <p>John Cowles helped with the port to Windows (98) by answering questions and
 running tests.</p>

 <p>Ruben Gamboa created a modification of ACL2 to allow reasoning about the
 real numbers using non-standard analysis.  His work has been incorporated into
 the ACL2 distribution; see @(see real).</p>

 <p>Rob Sumners has made numerous useful suggestions.  In particular, he has
 designed and implemented improvements for @(see stobj)s and been key in our
 development of locally-bound stobjs; see @(see note-2-6).</p>

 <p>Robert Krug has designed and implemented many changes in the vicinity of
 the linear arithmetic package and its connection to type-set and rewrite.  He
 was also instrumental in the development of @(see extended-metafunctions).</p>

 <p>Pete Manolios has made numerous useful suggestions.  In particular, Pete
 helped us to organize the first workshop and was a wonderful equal partner
 with the two of us (Kaufmann and Moore) in producing the books that arose from
 that workshop.  Pete and his student, Daron Vroon, provided the current
 implementation of @(see ordinals).</p>

 <p>Jared Davis, Sol Swords, and David Rager have our gratitude for starting
 the <a href='https://github.com/acl2/acl2/'>ACL2+Books repository</a>.</p>

 <p>We thank David L. Rager for contributing an initial version of the support
 for @(see parallelism) in an experimental extension of ACL2.</p>

 <p>Bob Boyer and Warren A. Hunt, Jr. developed a canonical representation for
 ACL2 data objects, applicative hash tables, and a function memoization
 mechanism to facilitate reuse of previously computed results.  Subsequently,
 Jared Davis and Sol Swords made further contributions.  We thank them all for
 this work, most of which has been incorporated into ACL2; see @(see
 hons-and-memoization).</p>

<p>Other contributions to the ACL2 system continue to be made by members of the
 ACL2 community.  In particular, following the first Developers Workshop in
 May, 2017 through the time of this writing in November, 2019, such
 contributors include Alessandro Coglio, Keshav Kini, Mihir Mehta, Pete
 Manolios, and especially Sol Swords, while Eric Smith and many others have
 suggested changes that we have implemented, often by providing helpful
 examples.  The @(see release-notes) detail such contributions as well as many
 suggestions from the community for improvements that we ultimately
 implemented.</p>

 <p>We also thank the contributors to the ACL2 @(see workshops) for some
 suggested improvements and for the extensive collection of publicly
 distributed benchmark problems.  And we thank participants at the ACL2 seminar
 at the University of Texas for useful feedback.  More generally, we thank the
 ACL2 community for feedback, contributed @(see books) (see @(see
 community-books)), and their interest in the ACL2 project.</p>

 <p><i>Regarding the documentation:</i></p>

 <blockquote><p>Bill Young wrote significant portions of the original
 @('acl2-tutorial') section of the ACL2 documentation, including what is now
 called @(see alternative-introduction).  This was an especially important task
 in the early years when there was no guide for how to use ACL2 and we are very
 grateful.  He, Bishop Brock, Rich Cohen, and Noah Friedman read over
 considerable amounts of the documentation, and made many useful comments.
 Others, particularly Bill Bevier and John Cowles, have also made useful
 comments on the @(see documentation).</p>

 <p>Art Flatau helped develop the ACL2 markup language in which ACL2 @(see
 documentation) was originally developed, along with translators from that
 language to Texinfo and HTML.  Michael ``Bogo'' Bogomolny created a search
 engine, beginning with Version 2.6, and for that purpose modified the HTML
 translator to create one file per topic (a good idea in any case).</p>

 <p>Laura Lawless provided many hours of help in marking up appropriate parts
 of the @(see documentation) in typewriter font.</p>

 <p>Noah Friedman developed an Emacs tool that helped us insert ``invisible
 links'' into the @(see documentation), which improve the usability of that
 documentation under HTML readers such as Mosaic.</p>

 <p>Richard Stallman contributed a texinfo patch, to be found in the file
 @('doc/texinfo.tex').</p>

 <p>Jared Davis created the @(see xdoc) system that is now the basis not only
 for the ACL2 system @(see documentation) (file
 @('books/system/doc/acl2-doc.lisp')), but also for the @(see community-books)
 documentation.</p>

 </blockquote>

 <p>We thank Blake Grugett for designing the current version of the ACL2 logo
 (which for example appears on the ACL2 home page), based on an original design
 created in the 1990s by Computational Logic, Inc.</p>

 ")

(defxdoc acl2
  :parents (top)
  :short "ACL2 system documentation"
  :long "<p>Those topics that pertain to the ACL2 system belong under this node
 of the @(see documentation).  See @(see top) for the top node of this manual,
 under which may be found many topics pertaining to the @(see
 community-books).</p>")

(defxdoc |ACL2 Characters|
  :parents (|Pages Written Especially for the Tours|)
  :short "ACL2 Characters"
  :long "<p>ACL2 accepts 256 distinct characters, which are the characters
 obtained by applying the function @(tsee code-char) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>
 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
 constant expression @('*standard-chars*').</p>

 <p>The standard character constants are written by writing a hash mark
 followed by a backslash (#\) followed by the character.</p>

 <p>The function @(tsee characterp) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>
 recognizes characters.  For more details, See @(see characters) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>.</p>")

(defxdoc |ACL2 Conses or Ordered Pairs|
  :parents (|Pages Written Especially for the Tours|)
  :short "ACL2 Conses or Ordered Pairs"
  :long "<p>The function @(tsee cons) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>
 creates an ordered pair.  @(tsee Car) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see> and
 @(tsee cdr) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> return the first and second components,
 respectively, of an ordered pair.  The function @(tsee consp) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>
 recognizes ordered pairs.</p>

 <p>Ordered pairs are used to represent lists and trees.  See any Common Lisp
 documentation for a discussion of how list constants are written and for the
 many list processing functions available.  Also, see @(see programming) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>
 where we list all the ACL2 primitive functions.</p>

 <p>Here are some examples of list constants to suggest their syntax.</p>

 @({
  '(a . b)                ; a pair whose car is 'a and cdr is 'b
  '(a . nil)              ; a pair whose car is 'a and cdr is nil
  '(a)                    ; another way to write the same thing
  '(a b)                  ; a pair whose car is 'a and cdr is '(b)
  '(a b c)                ; a pair whose car is 'a and cdr is '(b c)
                          ;  i.e., a list of three symbols, a, b, and c.
  '((a . 1) (b . 2))      ; a list of two pairs
 })

 <p>It is useful to distinguish ``proper'' conses from ``improper'' ones, the
 former being those cons trees whose right-most branch terminates with
 @('nil').  A ``true list'' (see @(see true-listp) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>) is
 either @('nil') or a proper cons.  @('(A b c . 7)') is an improper cons and
 hence not a true list.</p>")

(defxdoc |ACL2 Strings|
  :parents (|Pages Written Especially for the Tours|)
  :short "ACL2 Strings"
  :long "<p>Strings of ACL2 <see topic='@(url
 |ACL2 Characters|)'>characters</see> are written as sequences of characters
 delimited by ``double quotation marks''
 (").  To put a double quotation mark in a string (or, any other character
 such as backslash or newline that seems to cause problems), escape it by
 preceding it with a backslash (\).</p>

 <p>The function @(tsee stringp) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>
 recognizes strings and @(tsee char) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>
 will fetch the nth character of a string.  There are many other primitives for
 handling strings, such as @(tsee string<) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see> for
 comparing two strings lexicographically.  We suggest you See @(see
 programming) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> where we list all of the primitive ACL2 functions.
 Alternatively, see any Common Lisp language documentation.</p>")

(defxdoc |ACL2 Symbols|
  :parents (|Pages Written Especially for the Tours|)
  :short "ACL2 Symbols"
  :long "<p>Common Lisp's symbols are a data type representing words.  They are
 frequently regarded as atomic objects in the sense that they are not
 frequently broken down into their constituents.  Often the only important
 properties of symbols is that they are not numbers, characters, strings, or
 lists and that two symbols are not equal if they look different (!).  Examples
 of symbols include @('PLUS') and @('SMITH::ABC').  All function and variable
 names in ACL2 are symbols.  When symbols are used as constants they must be
 quoted, as in @(''PLUS').</p>

 <p>The symbol @('T') is commonly used as the Boolean ``true.''  The symbol
 @('NIL') is commonly used both as the Boolean ``false'' and as the ``empty
 list.''  Despite sometimes being called the ``empty list'' @('NIL') is a
 <b>symbol</b> not an ``empty cons.''  Unlike other symbols, @('T') and
 @('NIL') may be used as constants without quoting them.</p>

 <p>Usually, symbols are written as sequences of alphanumeric characters other
 than those denoting numbers.  Thus, @('A12'), @('+1A') and @('1+') are symbols
 but @('+12') is a number.  Roughly speaking, when symbols are read lower case
 characters are converted to upper case, so we frequently do not distinguish
 @('ABC') from @('Abc') or @('abc').  Click <see topic='@(url
 symbols)'>here</see> <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> for information about case conversion
 when symbols are read.  However, any character can be used in a symbol, but
 some characters must be ``escaped'' to allow the Lisp reader to parse the
 sequence as a symbol.  For example, @('|Abc|') is a symbol whose first
 character is capitalized and whose remaining characters are in lower case.
 @('|An odd duck|') is a symbol containing two #\Space characters.  See any
 Common Lisp documentation for the syntactic rules for symbols.</p>

 <p>Technically, a symbol is a special kind of pair consisting of a package
 name (which is a string) and a symbol name (which is also a string).  (See
 @(see symbol-package-name) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see> and
 see @(see symbol-name) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>.)  The symbol SMITH::ABC is said to be in package
 "SMITH" and to have the symbol name "ABC".  The symbol @('ABC') in package
 "SMITH" is generally not equal to the symbol @('ABC') in package "JONES".
 However, it is possible to ``import'' symbols from one package into another
 one, but in ACL2 this can only be done when the package is created.  (See
 @(see defpkg) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>.)  If the @(tsee current-package) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see> is
 "SMITH" then @('SMITH::ABC') may be more briefly written as just @('ABC').
 @(tsee Intern) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> ``creates'' a symbol of a given name in a given
 package.</p>")

(defxdoc |ACL2 System Architecture|
  :parents (|Pages Written Especially for the Tours|)
  :short "ACL2 System Architecture"
  :long "<p><see topic='@(url
 |Rewrite Rules are Generated from DEFTHM Events|)'><img
 src='res/tours/walking.gif'></img></see></p>

 <p><img src='res/tours/acl2-system-architecture.gif'></img></p>

 <p>The user interacts with the theorem prover by giving it definitions,
 theorems and advice.  Most often the advice is about how to store each proved
 theorem as a rule.  Sometimes the advice is about how to prove a specific
 theorem.</p>

 <p>The database consists of all the rules ACL2 ``knows.''  It is possible to
 include in the database all of the rules in some certified file of other
 events.  Such certified files are called @(see books) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>.</p>

 <p>Interesting proofs are usually built on top of many books, some of which
 are written especially for that problem domain and others of which are about
 oft-used domains, like arithmetic or list processing.  ACL2's distribution
 includes many books written by users.  See the ``books'' link under the
 <b>Lemma Libraries and Utilities</b> <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>
 link of the ACL2 home page.</p>

 <p><see topic='@(url |Rewrite Rules are Generated from DEFTHM Events|)'><img
 src='res/tours/walking.gif'></img></see></p>")

(defxdoc |ACL2 as an Interactive Theorem Prover|
  :parents (|Pages Written Especially for the Tours|)
  :short "ACL2 as an Interactive Theorem Prover"
  :long "<p>The ACL2 theorem prover finds proofs in the ACL2 logic.  It can be
 automatic.  But most often the user must help it.</p>

 <p><img src='res/tours/interactive-theorem-prover.gif'></img></p>

 <p>The user usually guides ACL2 by suggesting that it first prove key
 <b>lemmas</b>.  Lemmas are just theorems used in the proofs of other
 theorems.</p>")

(defxdoc |ACL2 as an Interactive Theorem Prover (cont)|
  :parents (|Pages Written Especially for the Tours|)
  :short "ACL2 as an Interactive Theorem Prover (cont)"
  :long "<p><see topic='@(url |ACL2 System Architecture|)'><img
 src='res/tours/walking.gif'></img></see></p>

 <p>When ACL2 proves a lemma, it is converted into one or more <b>rules</b> and
 stored in a <b>database</b>.  The theorem prover is <b>rule-driven</b>.  By
 proving lemmas you can configure ACL2 to behave in certain ways when it is
 trying to prove formulas in a certain problem domain.  The expert user can
 make ACL2 do amazingly ``smart'' looking things.</p>

 <p>But it would be wrong to think that ACL2 <i>knows</i> the mathematical
 content of a formula just because it has proved it.  What ACL2 knows &mdash;
 all ACL2 knows &mdash; is what is encoded in its rules.  There are many types
 of rules (see @(see rule-classes) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>).</p>

 <p>Many formulas can be effectively coded as rules.  But by the same token, it
 is possible to encode a formula as a rule that is so ineffective it cannot
 even prove itself!</p>

 <p>The way a formula is stored as a rule is entirely up to the user.  That is,
 <b>you</b> determine how ACL2 should use each formula that it proves.</p>

 <p>The most common kind of rule is the <b>rewrite rule</b>.  It is so common
 that if you don't tell ACL2 how to store a formula, it stores it as a rewrite
 rule.</p>

 <p><see topic='@(url |ACL2 System Architecture|)'><img
 src='res/tours/walking.gif'></img></see></p>")

(defxdoc |ACL2 is an Untyped Language|
  :parents (|Pages Written Especially for the Tours|)
  :short "ACL2 is an Untyped Language"
  :long "<p>The example</p>

 <code>
 ACL2 !&gt;<b>(app '(a b c) 27)</b>
 (A B C . 27)
 </code>

 <p>illustrates the fact that ACL2's logic is untyped (click <see topic='@(url
 |About Types|)'>here</see> for a brief discussion of the typed versus untyped
 nature of the logic).</p>

 <p>The definition of @('app') makes no restriction of the arguments to lists.
 The definition says that if the first argument satisfies @(tsee endp) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>
 then return the second argument.  In this example, when @('app') has recursed
 three times down the @('cdr') of its first argument, @(''(a b c)'), it reaches
 the final @('nil'), which satisfies @('endp'), and so 27 is returned.  It is
 naturally consed into the emerging list as the function returns from
 successive recursive calls (since @('cons') does not require its arguments to
 be lists, either).  The result is an ``improper'' list, @('(a b c . 27)').</p>

 <p>You can think of @('(app x y)') as building a binary tree by replacing the
 right-most tip of the tree @('x') with the tree @('y').</p>")

(defxdoc acl2-as-standalone-program
  :parents (acl2-tutorial)
  :short "Calling ACL2 from another program"
  :long "<p>ACL2 is intended for interactive use.  It is generally unrealistic
 to expect it to prove theorems fully automatically; see @(see the-method), and
 see @(see introduction-to-the-theorem-prover) for a more detailed
 tutorial.</p>

 <p>Nevertheless, here we describe an approach for how to call the ACL2 theorem
 prover noninteractively.  These steps can of course be modified according to
 your needs.  Here, we illustrate how to call ACL2 from another Lisp program
 (or an arbitrary program) to attempt to prove an arithmetic theorem.</p>

 <p>See also @(see interfacing-tools).  In particular, if you want to make a
 command-line tool to ACL2 with options, you may be interested in @(see
 oslib::argv), @(see getopt::getopt), and especially @(see getopt-demo::demo2).
 Alternately, if you want to develop a server application on top of ACL2, you
 might consider @(see bridge::bridge).</p>

 <h3>Step 1</h3>

 <p>Build a suitable ACL2 image by starting ACL2 and then executing the
 following forms.  In particular, these define a macro, @('try-thm'), that
 causes ACL2 to exit with an exit status indicating success or failure of a
 proof attempt.</p>

 @({
  (include-book "arithmetic-5/top" :dir :system)
  (defmacro try-thm (&rest args)
    `(mv-let (erp val state)
             (with-prover-time-limit 3 (thm ,@args))
             (declare (ignore val))
             (prog2$ (if erp (exit 1) (exit 0)) state))))
  (reset-prehistory) ; optional
  :q
  (save-exec "arith-acl2" "Included arithmetic-4/top")
 })

 <p>If you prefer, above you can replace 3 by some other number of seconds as a
 time limit for the prover.  Also, you can replace</p>

 @({
  (with-prover-time-limit 3 (thm ,@args))
 })

 <p>by</p>

 @({
  (with-output :off :all (with-prover-time-limit 3 (thm ,@args)))
 })

 <p>if you want to turn off output.  It may be best to leave the output on,
 instead eliminating it in the calling program (see Step 3 below).</p>

 <h3>Step 2</h3>

 <p>Try a little test.  In that same directory try this:</p>

 @({
  echo '(try-thm (equal x x))' | ./arith-acl2
  echo $?
 })

 <p>The exit status should be 0, indicating success.  Now try this:</p>

 @({
  echo '(try-thm (not (equal x x)))' | ./arith-acl2
  echo $?
 })

 <p>The exit status should be 1, indicating failure.</p>

 <h3>Step 3</h3>

 <p>Create a shell script that automates Step 2, for example:</p>

 @({
  #!/bin/sh
  (echo "(try-thm $1)" | ./arith-acl2) >& /dev/null
  exit $?
 })

 <h3>Step 4</h3>

 <p>Try your script from a Lisp program, if you like.  Here is how you can do
 it in SBCL, for example.  (Different Lisps have different ways to do this, as
 summarized in function @('system-call') in ACL2 source file
 @('acl2-init.lisp').)</p>

 @({
  (defun provable? (x)
    (let ((status
           (process-exit-code
            (sb-ext:run-program "./try-thm.sh" (list (format nil "~s" x))
                                :output t :search t))))
      (eql status 0)))
 })

 <p>Then here is a log:</p>

 @({
    * (provable? '(equal x y))

    NIL
    * (provable? '(equal x x))

    T
    *
 })

 <p>Certainly refinements are possible &mdash; for example the above doesn't
 distinguish between unprovable and ill-formed input.  But it's a start.</p>

 ")

(defxdoc acl2-built-ins
  :parents (programming)
  :short "''Catch-all'' topic for built-in ACL2 functions"
  :long "<p>This @(see documentation) topic is a parent topic under which we
 include documentation for built-in functions, macros, and special forms that
 are typically used in @(see programming).  For others, including those
 typically used as top-level commands or those that create @(see events)
 (@(tsee defun), @(tsee defmacro), @(tsee 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.</p>

 <p>If you are already familiar with Common Lisp (or even some other Lisp
 variant), then you may find it helpful to start with the topic, @(see
 introduction-to-programming-in-acl2-for-those-who-know-lisp).</p>

 <p>See any documentation for Common Lisp for more details on many of these
 functions.</p>")

(defxdoc acl2-count
  :parents (basics acl2-built-ins)
  :short "A commonly used measure for justifying recursion"
  :long "<p>@('(Acl2-count x)') returns a nonnegative integer that indicates
 the ``size'' of its argument @('x').</p>

 <p>All @(see characters) and symbols have @('acl2-count 0').  The
 @('acl2-count') of a string is the number of @(see characters) in it, i.e.,
 its length.  The @('acl2-count') of a @(tsee cons) is one greater than the sum
 of the @('acl2-count')s of the @(tsee car) and @(tsee cdr).  The
 @('acl2-count') of an integer is its absolute value.  The @('acl2-count') of a
 rational is the sum of the @('acl2-count')s of the numerator and denominator.
 The @('acl2-count') of a complex rational is one greater than the sum of the
 @('acl2-count')s of the real and imaginary parts.</p>

 @(def acl2-count)")

(defxdoc acl2-customization
  :parents (miscellaneous)
  :short "File of initial commands for ACL2 to run at @(see startup)"
  :long "<p>ACL2 provides a mechanism to load automatically a so-called ``ACL2
 customization file,'' via @(tsee ld), the first time @(tsee lp) is called in
 an ACL2 session.  ACL2 looks for this file as follows.</p>

 <ol>

 <li>If the host Lisp reads a non-empty value for the system's
 environment variable @('ACL2_CUSTOMIZATION'), then that string value is used
 for the customization file name.  In this case, if the file does not exist or
 if the string is "NONE" then there is no customization file.  Notes:

     <ul>

     <li>If the customization file name is a relative pathname (see @(see
     pathname)), then the pathname is considered relative to the connected book
     directory (see @(see cbd)).</li>

     <li>If this variable is not already defined, then its value is set to
     @('NONE') when books are certified using @(see BUILD::cert.pl) or other,
     legacy Make-based certification tools.</li>

     </ul></li>

 <li>Otherwise (empty environment variable value), file
 @('"acl2-customization.lsp"') or @('"acl2-customization.lisp"') on the
 connected book directory (see @(see cbd)), generally the current directory, is
 the customization file (in that order) if either exists.</li>

 <li>Otherwise file @('"acl2-customization.lsp"') or
 @('"acl2-customization.lisp"') on your home directory is the customization
 file (in that order), if either exists (except, this case is skipped on
 Windows operating systems.</li>

 </ol>

 <p>Except for the fact that this @(tsee ld) command is not typed explicitly by
 you, it is a standard @(tsee ld) command except that any settings of @(tsee
 ld) specials are remembered once this call of @(tsee ld) has completed other
 than @(tsee ld-error-action), which will always be @(':command-conventions')
 after that call of @('ld') completes.  For example, suppose that you start
 your customization file with @('(set-ld-skip-proofsp t state)'), so that
 proofs are skipped as it is loaded with @(tsee ld).  Then the @(tsee ld)
 special @(tsee ld-skip-proofsp) will remain @('t') after the @(tsee ld) has
 completed, causing proofs to be skipped in your ACL2 session, unless your
 customization file sets this variable back to @('nil'), say with
 @('(set-ld-skip-proofsp nil state)').</p>

 <p>If the customization file exists, it is loaded with @(tsee ld) using the
 usual default values for the @(tsee ld) specials (see @(see ld)) except that
 @(':ld-error-action') is @(':error').  If an error is encountered, then no
 subsequent forms in the file will be evaluated and ACL2 will quit
 immediately.</p>

 <p>To create a customization file it is recommended that you first give it a
 name other than @('"acl2-customization.lsp"') or
 @('"acl2-customization.lisp"') so that ACL2 does not try to include it
 prematurely when you next enter @(tsee lp).  Then, while in the uncustomized
 @(tsee lp), explicitly invoke @(tsee ld) on your evolving (but renamed)
 customization file until all forms are successfully evaluated.  The same
 procedure is recommended if for some reason ACL2 cannot successfully evaluate
 all forms in your customization file: temporarily rename your customization
 file so that ACL2 does not try to @(tsee ld) it automatically and then debug
 the new file by explicit calls to @(tsee ld).</p>

 <p>WARNING!  If you certify a book after the (automatic) loading of a
 customization file, the forms in that file will be part of the @(see
 portcullis) of the @(see books) you certify!  That is, the forms in your
 customization file at certification time will be loaded whenever anybody uses
 the @(see books) you are certifying.  Since customization files generally
 contain idiosyncratic @(see command)s, you may not want yours to be part of
 the @(see books) you create for others.  Thus, if you have a customization
 file then you may want to invoke @(':')@(tsee ubt)@(' 1') before certifying
 any @(see books); alternatively, see @(see certify-book!) for automatic
 invocation of @(tsee ubt).</p>

 <p>On the other hand, if you wish to prevent undoing commands from the
 customization file, see @(see reset-prehistory).</p>

 <p>Note that except on Windows-based systems, if there is a file
 @('acl2-init.lsp') in your home directory, then it will be loaded into raw
 Lisp when ACL2 is invoked.</p>

 <h3>Silent loading of ACL2 customization files</h3>

 <p>When the environment variable @('ACL2_CUSTOMIZATION_QUIET') is set and not
 @('""'), there will generally be no output from ACL2 customization.  A
 special value of @('"all"') for this variable will cause continued minimal
 output after startup, as explained in the following remark.</p>

 <p>Technical Remark.  For quiet loading of acl2-customization files, @(tsee
 ld) specials are bound to the following values.</p>

 @({
 ld-verbose = nil
 ld-pre-eval-print = :never
 ld-post-eval-print = nil
 ld-prompt = nil
 })

 <p>These @('ld') specials are returned to their normal values after loading an
 ACL2 customization file, with one exception: if @('ACL2_CUSTOMIZATION_QUIET')
 has value @('"ALL"') (or @('"all"'); the case is irrelevant), then those
 values are retained in the ACL2 loop even after customization completes.</p>")

(defxdoc acl2-defaults-table
  :parents (table)
  :short "A @(see table) specifying certain defaults, e.g., the default @(see defun-mode)"
  :long "@({
  Example Forms:
  (table acl2-defaults-table :defun-mode) ; current default defun-mode
  (table acl2-defaults-table :defun-mode :program)
             ; set default defun-mode to :program
 })

 <p>See @(see table) for a discussion of tables in general.  The legal keys for
 this @(see table) are shown below.  They may be accessed and changed via the
 general mechanisms provided by @(see table)s.  However, there are often more
 convenient ways to access and/or change the defaults.  (See also the note
 below.)</p>

 @({
  :user
 })

 <p>The @(':user') key is for ACL2 users; the system does not consult this key
 or set it (other than as part of general @('acl2-defaults-table ')
 maintenance).  Its value is required to be an association list (@(tsee
 alistp)), so that different users can read and write their ``own'' keys.  For
 example, suppose user Joe uses key @(':j') while user Mary uses key @(':m');
 then we could see a value for @(':user') of @('((:j . 3) (:m . 4))') after Joe
 sets his value to 3 and Mary sets her value to 4.</p>

 @({
  :defun-mode
 })

 <p>the default @(see defun-mode), which must be @(':')@(tsee program) or
 @(':')@(tsee logic).  See @(see defun-mode) for a general discussion of @(see
 defun-mode)s.  The @(':')@(tsee defun-mode) key may be conveniently set by
 keyword commands naming the new @(see defun-mode), @(':')@(tsee program) and
 @(':')@(tsee logic).  See @(see program) and see @(see logic).</p>

 @({
  :enforce-redundancy
 })

 <p>if @('t'), cause ACL2 to insist that most events are redundant (see @(see
 redundant-events)); if @(':warn'), cause a warning instead of an error for
 such non-redundant events; else, @('nil').  See @(see
 set-enforce-redundancy).</p>

 @({
  :verify-guards-eagerness
 })

 <p>an integer between 0 and 3 indicating how eager the system is to verify the
 @(see guard)s of a @(see defun) event.  See @(see
 set-verify-guards-eagerness).</p>

 @({
  :compile-fns
 })

 <p>When this key's value is @('t'), functions are compiled when they are
 @(tsee defun)'d; otherwise, the value is @('nil').  (Except, this key's value
 is ignored when explicit compilation is suppressed; see @(see compilation).)
 To set the flag, see @(see set-compile-fns).</p>

 @({
  :measure-function
 })

 <p>the default measure function used by @(tsee defun) when no @(':measure') is
 supplied in @(tsee xargs).  The default measure function must be a function
 symbol of one argument. Let @('mfn') be the default measure function and
 suppose no @(':measure') is supplied with some recursive function definition.
 Then @(tsee defun) finds the first formal, @('var'), that is tested along
 every branch and changed in each recursive call.  The system then ``guesses''
 that @('(mfn var)') is the @(':measure') for that @(tsee defun).</p>

 @({
  :well-founded-relation
 })

 <p>the default well-founded relation used by @(tsee defun) when no
 @(':well-founded-relation') is supplied in @(tsee xargs).  The default
 well-founded relation must be a function symbol, @('rel'), of two arguments
 about which a @(':well-founded-relation') rule has been proved.  See @(see
 well-founded-relation-rule).</p>

 @({
  :bogus-defun-hints-ok
 })

 <p>When this key's value is @('t'), ACL2 allows @(':hints') and also
 @(':measure') for nonrecursive function definitions.  Otherwise, the value is
 @('nil') (the default) or @(':warn') (which makes the check but merely warns
 when the check fails).  See @(see set-bogus-defun-hints-ok) and @(see
 set-bogus-measure-ok).</p>

 @({
  :bogus-mutual-recursion-ok
 })

 <p>When this key's value is @('t'), ACL2 skips the check that every function
 in a @(tsee mutual-recursion) (or @(tsee defuns)) ``clique'' calls at least
 one other function in that ``clique.''  Otherwise, the value is @('nil') (the
 default) or @(':warn') (which makes the check but merely warns when the check
 fails).  See @(see set-bogus-mutual-recursion-ok).</p>

 @({
  :irrelevant-formals-ok
 })

 <p>When this key's value is @('t'), the check for irrelevant formals is
 bypassed; otherwise, the value is the keyword @('nil') (the default) or
 @(':warn') (which makes the check but merely warns when the check fails).  See
 @(see irrelevant-formals) and see @(see set-irrelevant-formals-ok).</p>

 @({
  :ignore-ok
 })

 <p>When this key's value is @('t'), the check for ignored variables is
 bypassed; otherwise, the value is the keyword @('nil') (the default) or
 @(':warn') (which makes the check but merely warns when the check fails).  See
 @(see set-ignore-ok).</p>

 @({
  :bdd-constructors
 })

 <p>This key's value is a list of function symbols used to define the notion of
 ``BDD normal form.''  See @(see bdd-algorithm) and see @(see hints).</p>

 @({
  :ttag
 })

 <p>This key's value, when non-@('nil'), allows certain operations that extend
 the trusted code base beyond what is provided by ACL2.  See @(see defttag).
 See @(see defttag).</p>

 @({
  :state-ok
 })

 <p>This key's value is either @('t') or @('nil') and indicates whether the
 user is aware of the syntactic restrictions on the variable symbol @('STATE').
 See @(see set-state-ok).</p>

 @({
  :backchain-limit
 })

 <p>This key's value is a list of two ``numbers.''  Either ``number'' may
 optionally be @('nil'), which is treated like positive infinity.  The numbers
 control backchaining through hypotheses during @(see type-reasoning) and
 rewriting.  See @(see backchain-limit).</p>

 @({
  :default-backchain-limit
 })

 <p>This key's value is a list of two ``numbers.''  Either ``number'' may
 optionally be @('nil'), which is treated like positive infinity.  The numbers
 are used respectively to set the backchain limit of a rule if one has not been
 specified. See @(see backchain-limit).</p>

 @({
  :step-limit
 })

 <p>This key's value is either @('nil') or a natural number not exceeding the
 value of @('*default-step-limit*').  If the value is @('nil') or the value of
 @('*default-step-limit*'), there is no limit on the number of ``steps'' that
 ACL2 counts during a proof: currently, the number of top-level rewriting
 calls.  Otherwise, the value is the maximum number of such calls allowed
 during evaluation of any event.  See @(see set-prover-step-limit).</p>

 @({
  :rewrite-stack-limit
 })

 <p>This key's value is a nonnegative integer less than @('(expt 2 28)').  It
 is used to limit the depth of calls of ACL2 rewriter functions.  See @(see
 rewrite-stack-limit).</p>

 @({
  :let*-abstractionp
 })

 <p>This key affects how the system displays subgoals.  The value is either
 @('t') or @('nil').  When t, let* expressions are introduced before printing
 to eliminate common subexpressions.  The actual goal being worked on is
 unchanged.</p>

 @({
  :case-split-limitations
 })

 <p>This key's value is a list of two ``numbers.''  Either ``number'' may
 optionally be @('nil'), which is treated like positive infinity.  The numbers
 control how the system handles case splits in the simplifier.  See @(see
 set-case-split-limitations).</p>

 @({
  :include-book-dir-alist
 })

 <p>This key's value is used by @(tsee include-book)'s @(':DIR') argument to
 associate a directory with a keyword.  It need not associate a value with
 @(':SYSTEM'), to denote the @('books/') directory (see @(see community-books);
 see @(see include-book), in particular the section on ``Books Directory.''
 Also see @(tsee add-include-book-dir), @(tsee add-include-book-dir!), and
 @(tsee project-dir-alist).</p>

 @({
  :match-free-default
 })

 <p>This key's value is either @(':all'), @(':once'), or @('nil').  See @(see
 set-match-free-default).</p>

 @({
  :match-free-override
 })

 <p>This key's value is a list of runes.  See @(see
 add-match-free-override).</p>

 @({
  :match-free-override-nume
 })

 <p>This key's value is an integer used in the implementation of @(see
 add-match-free-override), so that only existing runes are affected by that
 event.</p>

 @({
  :non-linearp
 })

 <p>This key's value is either @('t') or @('nil') and indicates whether the
 user wishes ACL2 to extend the linear arithmetic decision procedure to include
 non-linear reasoning.  See @(see non-linear-arithmetic).</p>

 @({
  :tau-auto-modep
 })

 <p>This key's value is either @('t') or @('nil') and indicates whether the
 user wishes ACL2 to look for opportunities to create @(':')@(tsee tau-system)
 rules from all suitable @('defun')s and from all suitable @('defthm')s (with
 non-@('nil') @(':')@(tsee rule-classes)).  See @(see set-tau-auto-mode).</p>

 @({
  :subgoal-loop-limits
 })

 <p>This key's value must be a @(tsee cons) whose @(tsee car) is either
 @('nil') or a natural number and whose @(tsee cdr) is @('nil') or a natural
 number.  See @(see set-subgoal-loop-limits).</p>

 @({
  :ruler-extenders
 })

 <p>This key's value may be a list of symbols, indicating those function
 symbols that are not to block the collection of rulers; see @(see defun).
 Otherwise the value is @(':all') to indicate all function symbols, i.e., so
 that no function symbol blocks the collection of rulers.  If a list is
 specified (rather than @(':all')), then it may contain the keyword
 @(':lambdas'), which has the special role of specifying all @('lambda')
 applications.  No other keyword is permitted in the list.  See @(see
 rulers).</p>

 @({
  :memoize-ideal-okp
 })

 <p>This key's value must be either @('t'), @('nil'), or @(':warn').  If the
 value is @('nil') or not present, then it is illegal by default to @(see
 memoize) a @(':')@(tsee logic) mode function that has not been @(see
 guard)-verified (see @(see verify-guards)), sometimes called an ``ideal-mode''
 function.  This illegality is the default because such calls of such functions
 in the ACL2 loop are generally evaluated in the logic (using executable
 counterpart definitions; see @(see evaluation)), rather than directly by
 executing calls of the corresponding (memoized) raw Lisp function.  However,
 such a raw Lisp call can be made when the function is called by a @(':')@(tsee
 program) mode function, so we allow you to override the default behavior by
 associating the value @('t') or @(':warn') with the key
 @(':memoize-ideal-okp'), where with @(':warn') you get a suitable warning.
 Note that you can also allow memoization of ideal-mode functions by supplying
 argument @(':ideal-okp') to your memoization event (see @(see memoize)), in
 which case the value of @(':memoize-ideal-okp') in the
 @('acl2-defaults-table') is irrelevant.</p>

 @({
  :check-invariant-risk
 })

 <p>For an explanation of this key, see @(see set-check-invariant-risk).</p>

 @({
  :register-invariant-risk
 })

 <p>For an explanation of this key, see @(see set-register-invariant-risk).</p>

 @({
  :in-theory-redundant-okp
 })

 <p>When this key's value is @('t'), an @(tsee in-theory) event may be
 redundant.  See @(tsee set-in-theory-redundant-okp).</p>

 <p>Note: Unlike all other @(see table)s, @('acl2-defaults-table') can affect
 the soundness of the system.  The @(see table) mechanism therefore enforces on
 it a restriction not imposed on other @(see table)s: when @(tsee table) is
 used to update the @('acl2-defaults-table'), the key and value must be
 variable-free forms.  Thus, while</p>

 @({
  (table acl2-defaults-table :defun-mode :program),

  (table acl2-defaults-table :defun-mode ':program), and

  (table acl2-defaults-table :defun-mode (compute-mode *my-data*))
 })

 <p>are all examples of legal @(see events) (assuming @('compute-mode') is a
 function of one non-@(tsee state) argument that produces a @(see defun-mode)
 as its single value),</p>

 @({
  (table acl2-defaults-table :defun-mode (compute-mode (w state)))
 })

 <p>is not legal because the value form is @(tsee state)-sensitive.</p>

 <p>Consider for example the following three @(see events) which one might make
 into the text of a book.</p>

 @({
  (in-package "ACL2")

  (table acl2-defaults-table
    :defun-mode
    (if (ld-skip-proofsp state) :logic :program))

  (defun crash-and-burn (x) (car x))
 })

 <p>The second event is illegal because its value form is @(tsee
 state)-sensitive.  If it were not illegal, then it would set the @(':')@(tsee
 defun-mode) to @(':')@(tsee program) when the book was being certified but
 would set the @(see defun-mode) to @(':')@(tsee logic) when the book was being
 loaded by @(tsee include-book).  That is because during certification, @(tsee
 ld-skip-proofsp) is @('nil') (proof obligations are generated and proved), but
 during book inclusion @(tsee ld-skip-proofsp) is non-@('nil') (those
 obligations are assumed to have been satisfied.)  Thus, the above book, when
 loaded, would create a function in @(':')@(tsee logic) mode that does not
 actually meet the conditions for such status.</p>

 <p>For similar reasons, @(tsee table) @(see events) affecting
 @('acl2-defaults-table') are illegal within the scope of @(tsee local) forms.
 That is, the text</p>

 @({
  (in-package "ACL2")

  (local (table acl2-defaults-table :defun-mode :program))

  (defun crash-and-burn (x) (car x))
 })

 <p>is illegal because @('acl2-defaults-table') is changed locally.  If this
 text were acceptable as a book, then when the book was certified,
 @('crash-and-burn') would be processed in @(':')@(tsee program) mode, but when
 the certified book was included later, @('crash-and-burn') would have
 @(':')@(tsee logic) mode because the @(tsee local) event would be skipped.</p>

 <p>The text</p>

 @({
  (in-package "ACL2")

  (program) ;which is (table acl2-defaults-table :defun-mode :program)

  (defun crash-and-burn (x) (car x))
 })

 <p>is acceptable and defines @('crash-and-burn') in @(':')@(tsee program)
 mode, both during certification and subsequent inclusion.</p>

 <p>We conclude with important observations about the interaction of the
 @('acl2-defaults-table') with @(tsee include-book), @(tsee certify-book), and
 @(tsee encapsulate).  If the @('acl2-defaults-table') has value @('V') and you
 evaluate a call of @(tsee include-book), @(tsee certify-book), or @(tsee
 encapsulate), then the @('acl2-defaults-table') has value @('V') when that
 call returns.  Thus, if you want to set the @('acl2-defaults-table') in a way
 that persists, you need to do so using @(see command)s that are not inside
 @(see books).  It may be useful to set your favorite defaults in your @(tsee
 acl2-customization) file; see @(see acl2-customization).</p>

 <p>ACL2 disallows (for logical reasons) setting of the
 @('acl2-defaults-table') in the context of @('LOCAL').  Often it is easy
 simply to avoid wrapping an @('acl2-defaults-table') event, or a macro that
 generates such an event, inside a @('LOCAL'); after all, a local context is
 not useful when setting the @('acl2-defaults-table'), since that table is
 restored as discussed above upon completion of @(tsee include-book), @(tsee
 certify-book), and @(tsee encapsulate) forms.  Occasionally a bit more thought
 is required to work around this restriction, but usually it's not difficult to
 do so.  Suppose for example that you attempt to put following event form into
 a book.</p>

 @({
 (local (progn (defttag t) (defun foo (x) (sys-call x nil))))
 })

 <p>ACL2 responds with the following error message.</p>

 @({
 ACL2 Error in ( PROGN (DEFTTAG T) ...):  The form (DEFTTAG T)
 is not an embedded event form in the context of LOCAL
 because it implicitly sets the acl2-defaults-table in
 a local context; see :DOC acl2-defaults-table, in particular
 the explanation about this error message.  See :DOC
 embedded-event-form.
 })

 <p>A solution is to use @(tsee encapsulate) instead of (or in addition to)
 @(tsee progn), because @(tsee encapsulate) establishes a new context that is
 not considered within a surrounding @('LOCAL').  For example, the following
 replacement for the form above is legal in a book.</p>

 @({
 (local (encapsulate () (defttag t) (defun foo (x) (sys-call x nil))))
 })

 <p>To see that this works, try creating a file @('"foo.lisp"') whose first
 form is @('(in-package "ACL2")') and whose only other form is the one
 displayed just above.  Then the command @('(certify-book "foo" 0 t :ttags
 :all)') will successfully certify that book.</p>")

(defxdoc acl2-doc
  :parents (documentation)
  :short "A custom Emacs browser for reading ACL2 @(see documentation)"
  :long "<p>As discussed elsewhere (see @(see documentation)), the web-based
 @(`(:raw (combined-manual-ref))`) provides a way to browse the combined
 documentation for the ACL2 system and community books.  Such documentation can
 also be read at the terminal using the @(':')@(tsee doc) command, though
 documentation for @(see books) will only be included for those books that have
 been included in the session.  In this topic we describe how to browse the
 documentation using ACL2-Doc, a browser for reading
 documentation inside Emacs.  It supports reading the combined documentation
 (ACL2 plus books), but it also supports reading the ACL2-only manual as well
 as custom manuals.  We assume some familiarity with Emacs, for example, the
 notion of a ``prefix argument'': a numeric value given first with the
 @('meta') key (or, probably the @('control') key), for example, @('meta-0
 control-t g') or @('control-3 control-t /').</p>

 <p>Note: If you are not happy with the way text is displayed with ACL2-Doc,
 see @(see xdoc::terminal).</p>

 <p>While ACL2-Doc is much like Emacs Info, it is a separate system that
 provides some additional functionality.  ACL2-Doc is text-based.  Any word
 that names a topic is a link: you can hit the @('<Return>') key while standing
 on that topic to go to the page of documentation for that topic.  However,
 many links are shown explicitly, inside square brackets.  For example, here is
 a link that will take you to the BOOKS topic; it should show up surrounded by
 square brackets if you are now reading at the terminal or in ACL2-Doc, but
 there are no square brackets for this link if you are reading on the web.</p>

 <blockquote>

 <p>@(see books)</p>

 </blockquote>

 <p>It should be very rare for square brackets to be intended simply as square
 brackets, not as link indicators.</p>

 <p>In order to use ACL2-Doc, load into Emacs the distributed file
 <tt>acl2-doc.el</tt> from an appropriate directory; see @(see emacs).  This
 will happen automatically if you load <tt>emacs-acl2.el</tt> from an
 appropriate directory; again, see @(see emacs).  Then to start the browser at
 the top-level topic, either execute the Emacs command</p>

 @({
 meta-x acl2-doc
 })

 <p>or else type:</p>

 @({
 Control-t g
 })

 <p>Thus, you can put the following form in your @('.emacs') file if you want
 @('acl2-doc') to run automatically when Emacs starts up.</p>

 @({
 (acl2-doc)
 })

 <p>By default you will browse the ACL2+Books Manual, though if you are using a
 git version between ACL2 releases then you may be queried; more on that below.
 Or, see below for how to set a variable in your @('.emacs') file,
 @('*acl2-doc-manual-name*'), so that you will browse a custom manual.  You can
 enter the ACL2-Doc browser at a specific documentation topic as follows (in
 analogy to Emacs command @('Meta-.')):</p>

 @({
 Control-t .
 })

 <p>In each of the cases above, you will now be in a buffer called
 "<tt>acl2-doc</tt>", which will be displaying the top-level ACL2 topic in a
 special mode, the ACL2-Doc major mode.  That mode provides the following key
 bindings; you can also see these by typing <tt>Control-h m</tt> while in that
 buffer.</p>

 @({
  <Return>        acl2-doc-go!
  Shift-<Return>  acl2-doc-go!-new-buffer
  g               acl2-doc-go
  G               acl2-doc-go-new-buffer
  h               acl2-doc-help
  ?               acl2-doc-summary
  i               acl2-doc-index
  ,               acl2-doc-index-next
  <               acl2-doc-index-previous
  K               acl2-doc-kill-buffers
  l               acl2-doc-last
  n               acl2-doc-search-next
  p               acl2-doc-search-previous
  q               acl2-doc-quit
  r               acl2-doc-return
  s               acl2-doc-search
  S               acl2-doc-re-search
  t               acl2-doc-top
  u               acl2-doc-up
  w               acl2-doc-where
  SPC             scroll-up
  TAB             acl2-doc-tab
  <backtab> (which often is Shift-TAB):
                  acl2-doc-tab-back
  D               acl2-doc-rendered-combined-download
  H               acl2-doc-history
  I               acl2-doc-initialize
  /               acl2-doc-definition
  Control-t /     acl2-doc-definition
  W               acl2-doc-where-definition
 })

 <p>You can see the documentation for each of these in the usual way, using
 <tt>Control-h k {key}</tt> or <tt>Control-h f {command}</tt>.  Here is what
 you will find in each case if you do that.</p>

 @({
  <Return>      acl2-doc-go!
     Go to the topic occurring at the cursor position.  In the case
     of <NAME>, instead go to the source code definition of NAME for
     the current manual (as for `/', but without a minibuffer query).

  Shift-<Return>  acl2-doc-go!-new-buffer
     Go to the topic occurring at the cursor position in a new buffer.  In the
     case of <NAME>, instead go to the source code definition of NAME for the
     current manual (as for `/', but without a minibuffer query).  The new
     buffer's name reflects that topic name, but it stays the same even if the
     topic is subsequently changed there.

  g             acl2-doc-go
     Go to the specified topic; performs completion.  The new buffer's name
     reflects that topic name, but it stays the same even if the topic is
     subsequently changed there.

  G             acl2-doc-go-new-buffer
     Go to the specified topic in a new buffer; performs completion.

  h             acl2-doc-help
     Go to the ACL2-DOC topic to read about how to use the ACL2-Doc browser.

  ?             acl2-doc-summary
     Go to the ACL2-Doc-summary topic for one-line summaries of ACL2-Doc
     browser commands.

  i             acl2-doc-index
     Go to the specified topic or else one containing it as a substring;
     performs completion.  If the empty string is supplied, then go to the
     index buffer.  Otherwise, with prefix argument, consider only descendants
     of the topic supplied in response to a prompt.  Note that the index buffer
     is in ACL2-Doc mode; thus, in particular, you can type <RETURN> while
     standing on a topic in order to go directly to that topic.

  ,             acl2-doc-index-next
     Find the next topic containing, as a substring, the topic of the most
     recent i command.  Note: if this is the first "," or "<" after an
     exact match from "i", then start the topic search alphabetically from
     the beginning, but avoid a second hit on the original topic.  Also note
     that this command is buffer-local; it will follow the most recent i
     command executed in the current ACL2-Doc buffer.

  <             acl2-doc-index-previous
     Find the previous topic containing, as a substring, the topic of the most
     recent i command.  Note: if this is the first "," or "<" after an
     exact match from "i", then start the topic search alphabetically
     (backwards) from that exact match.  Also note that this command is
     buffer-local like the "," command.

  l             acl2-doc-last
     Go to the last topic visited in the current buffer.  This command is
     buffer-local.

  n             acl2-doc-search-next
     Find the next occurrence for the most recent search or regular expression
     search.  Note that this command is buffer-local; it will follow the most
     recent search initiated in the current buffer.

  p             acl2-doc-search-previous
     Find the previous occurrence for the most recent search or regular
     expression search.  Note: as for "n", the cursor will end up at the end
     of the match, and this command is buffer-local.

  q             acl2-doc-quit
     Quit the current ACL2-Doc buffer.

  K             acl2-doc-kill-buffers
     Kill all background ACL2-Doc buffers.  If invoked in an ACL2-Doc buffer,
     all ACL2-Doc buffers except the current one will be killed.  If invoked in
     any other buffer, all ACL2-Doc buffers will be killed.  With prefix
     argument, avoid a query that asks for confirmation.

  r             acl2-doc-return
     Return to the last topic visited in the current buffer, popping the stack
     of such topics.  This command is buffer-local.

  s             acl2-doc-search
     Search forward from the top of the manual for the input string.  If the
     search succeeds, then go to that topic with the cursor put immediately
     after the found text, with the topic name displayed in the minibuffer.
     With prefix argument, consider (also for subsequent "n" and "p"
     commands) only descendants of the topic supplied in response to a prompt.

  S             acl2-doc-re-search
     Perform a regular expression search, forward from the top of the manual,
     for the input string.  If the search succeeds, then go to that topic with
     the cursor put immediately after the found text, with the topic name
     displayed in the minibuffer.  With prefix argument, consider (also for
     subsequent "n" and "p" commands) only descendants of the topic
     supplied in response to a prompt.

  t             acl2-doc-top
     Go to the top topic.

  u             acl2-doc-up
     Go to the parent of the current topic.

  w             acl2-doc-where
     Display the topic name in the minibuffer, together with the manual name
     (ACL2+Books Manual or ACL2 User's Manual)

  SPC           scroll-up
     Scroll up (same as Control-v)

  TAB           acl2-doc-tab
     Visit the next link after the cursor on the current page, searching from
     the top if no link is below the cursor.

  <backtab> (which often is Shift-TAB):
                acl2-doc-tab-back
     Visit the previous link before the cursor on the current page, searching
     from the bottom if no link is below the cursor.

  D
     Download the ``bleeding edge'' ACL2+Books Manual from the web; then
     restart the ACL2-Doc browser to view that manual.  If this fails,
     evaluate Emacs variable acl2-doc-download-error for information on
     how to perform the download without Emacs.

  H             acl2-doc-history
     Visit a buffer that displays the names of all topics visited (in any
     ACL2-Doc buffer) in order, newest at the bottom.  That buffer is in
     acl2-doc mode; thus the usual acl2-doc commands may be used.  In
     particular, you can visit a displayed topic name by putting your cursor on
     it and typing <RETURN>.

  I             acl2-doc-initialize
     Restart the ACL2-Doc browser, clearing its state.  With a prefix argument,
     a query asks you to select the name of an available manual, using
     completion.  See the section on "Selecting a Manual", below,
     for more information.

  /             acl2-doc-definition
  (also control-t /)
     Find an ACL2 definition (in analogy to built-in Emacs command meta-.).
     With numeric prefix argument, find the next matching definition;
     otherwise, the user is prompted, where the default is the name at
     the cursor, obtained after stripping off any enclosing square
     brackets ([..]), angle brackets (<..>) as from srclink tags, and
     package prefixes.  With control-u prefix argument, search only
     ACL2 source definitions; otherwise, books are searched as well.
     As with built-in Emacs command meta-. , exact matches are given
     priority.  For more information, see the Section on "Selecting a
     Manual" in the acl2-doc online XDOC-based documentation.

  W             acl2-doc-where-definition
     Find an ACL2 definition.  This is the same as
     acl2-doc-definition (the acl2-doc `/' command, as well as
     control-t /), except that the default comes from the name of the
     current page's topic instead of the cursor position.  Searches
     are continued identically when control-t / is given a numeric
     prefix argument, regardless of whether the first command was /,
     control-t /, or W; thus, a search started with W can be continued
     with, for example, meta-3 control-t /.

 })

 <h4>Selecting a Manual, Tags Files, and Custom Manuals</h4>

 <p>ACL2-Doc can display the ACL2 User's Manual, which includes documentation
 for the ACL2 system but not for the @(see community-books).  But by default,
 ACL2-Doc will display the ACL2+Books Manual, which includes documentation for
 those books as well.  To change which of these two manuals you display, just
 give a prefix argument to the `@('I')' command, as described briefly
 above.</p>

 <p>For the `@('/')' and `@('W')' commands, you will need tags table files.
 These come with the ACL2 gzipped tarfile distribution, but if you obtain ACL2
 from github then you will need to build them.  The file @('"TAGS"') is used
 when these commands are given a prefix argument (to search only the ACL2
 sources), and is generated when building the @('saved_acl2') executable with
 `@('make')'.  Without a prefix argument the file @('"TAGS-acl2-doc"') is
 used for searching both the ACL2 sources and the books, and is created
 automatically if you build the manual by certifying community book
 @('books/doc/top.lisp').  You can also build @('"TAGS-acl2-doc"') by running
 the command @('bin/make-tags-acl2-doc.sh'), or by building the ACL2 executable
 after setting variable @('TAGS_ACL2_DOC') to a non-empty value other than
 @('SKIP') either on the command line with `@('make')' or, for example, by
 putting one of the following forms in your @('~/.cshrc') or @('~/.bashrc'),
 respectively.</p>

 @({
 setenv TAGS_ACL2_DOC t

 export TAGS_ACL2_DOC=t
 })

 <p>If you are using a git version of ACL2 and the books, between releases,
 then you may need to download an extra file in order to browse the ACL2+Books
 Manual.  Most likely you will just answer @('y') when queried about
 downloading the file when first using ACL2-Doc.  If you want more details, see
 the last of the notes in the ``Notes'' section below.</p>

 <p>As mentioned above, you can give the `@('I')' command a prefix argument in
 order to select a specific manual.  You will be asked for a name, which by
 default will be the most recently selected such name, if any.  As noted above,
 the only two manuals initially known to acl2-doc are the ACL2+Books Manual and
 the ACL2 User's Manual.  These have the names `@('combined')' and
 `@('acl2-only')', respectively.  You can also tell acl2-doc about a custom
 manual, by evaluating (in Emacs) the following form, e.g., by adding it to
 your @('~/.emacs') file before starting Emacs.  Here, @('filename') is the
 pathname of a file typically created by calling @(see
 xdoc::save-rendered).</p>

 @({
 (extend-acl2-doc-manual-alist
  'name          ; the name of the manual
  filename       ; documentation source, typically of the form *doc*.lsp
  'top           ; the top node name, typically TOP
  printname      ; optional print name (user-level name) of manual
  url            ; optional URL of gzipped file to download into filename
  tags-file-name ; optional tags filename (from output of etags)
  acl2-tags-file-name ; as above, but without files from books/ directory
  )
 })

 <p>For example, acl2-doc is initially built with the following two forms,
 which is why you can respond to the query mentioned above with `@('combined')'
 or `@('acl2-only')'.</p>

 @({
 (extend-acl2-doc-manual-alist
  'combined
  (concat *acl2-sources-dir*
          "books/system/doc/rendered-doc-combined.lsp")
  'TOP
  "ACL2+Books Manual"
  "https://acl2.org/doc/rendered-doc-combined.lsp.gz"
  (concat *acl2-sources-dir* "TAGS-acl2-doc")
  (concat *acl2-sources-dir* "TAGS"))

 (extend-acl2-doc-manual-alist
  'acl2-only
  (concat *acl2-sources-dir* "doc.lisp")
  'ACL2
  "ACL2 User's Manual"
  nil
  nil
  (concat *acl2-sources-dir* "TAGS"))
 })

 <p>Note that the first of these forms specifies the location of the
 @('"TAGS-acl2-doc"') and @('"TAGS"') files mentioned above, but the second
 only specifies @('"TAGS"') since the second form is for an ACL2-only manual
 (no books).</p>

 <p>If you want a specific manual to come up when you first run acl2-doc in an
 Emacs session, you can put the following into your @('.emacs') file, where
 @(''name') is the name a manual for which you have included a form
 @('(extend-acl2-doc-manual-alist 'name ...)') in your @('.emacs') file.</p>

 @({
 (setq *acl2-doc-manual-name* 'name)
 })

 <h4>Color</h4>

 <p>By default, links (indeed, any text) in square brackets will be shown in
 blue.  You can customize this behavior by setting (e.g., in your @('.emacs')
 file) the Emacs variable @('*acl2-doc-link-color*') to the desired link color,
 or to @('nil') if you don't want the links to be in color.  For example:</p>

 @({
 (setq *acl2-doc-link-color* "#FF0000") ; red
 (setq *acl2-doc-link-color* "Green")   ; green
 (setq *acl2-doc-link-color* nil)         ; no special color for links
 })

 <h4>Notes</h4>

 <ul>

 <li>You might find that when you attempt to follow @(see some-broken-link),
 you find yourself at the @(see broken-link) topic.  If you are using the ACL2
 User's Manual rather than the ACL2+Books Manual, the reason might be that
 @('some-broken-link') is documented in a book, not in the ACL2 system.  In
 that case, the @('broken-link') page will show you where to find that book;
 but if you want to read the documentation for @('some-broken-link') in the
 ACL2-Doc browser, you can do so by switching to the ACL2+Books Manual.  See
 the @('I') command, documented above.<p/></li>

 <li>Files with names ending in <tt>.acl2-doc</tt> will come up in ACL2-Doc
 mode.  Thus, you may wish to save a file with that extension, for example
 <tt>bookmarks.acl2-doc</tt>, that contains your favorite bookmarks.  You may
 wish to use the history command (<tt>H</tt>) to obtain a list of names of
 visited topics, in order to create an initial such file.<p/></li>

 <li>Many commands offer defaults, and many offer completion.  The default is
 determined by cursor position: if the cursor is sitting on a letter of a
 documentation topic name, or on a space character immediately after it, then
 that name will be offered as the default.  Completion tips:<p/>

 <ul>

 <li>Completion is carried out with the usual emacs ``@('completing-read')'';
 thus, for example, the character `@('?')' is a help key, so if you want that
 character as part of your topic name, prefix it with @('control-q').  For
 example, after the `@('g')' command you can go to the topic @(tsee mv?) by
 typing the character sequence @('<m,v,control-q ?>').</li>

 <li>To find completions that have package prefixes, type a colon (:) in the
 front, and completion will show matching topics.  For example, @('"g"')
 followed by @('":rew"') and then two tabs will show, at least in recent
 versions of Emacs, a list of topics that includes
 @('"ACL2-PC::REWRITE"').</li>

 </ul><p/></li>

 <li>Square brackets typically indicate documentation topic names, for example:
 <tt>[acl2-doc]</tt>.  (As mentioned above, there are occasional exceptions,
 where square brackets are simply part of the intended documentation text.)
 The square brackets are really there, for example when you are searching using
 "s", "S", or "n".  However, for purposes of determining the default
 name (see above), the only effect of the enclosing square brackets is to
 extend the region in which the default is offered.  For example, consider the
 string "<tt>[acl2-doc]</tt>": the default name of "<tt>acl2-doc</tt>" is
 offered if the cursor is on either square bracket.  But links have some
 idiosyncrasies.<p/>

 <ol>

   <li>Topic names, including links `<tt>[..]</tt>' to topic names, are printed
   relative to the ACL2 package.  Especially in the case of the ACL2+Books
   Manual, you may therefore see links that include package prefixes.  Here,
   for example, is a sentence from the documentation for @(see gl) in the
   ACL2+Books Manual.

   <code>
    We call these structures [gl::symbolic-objects].
   </code>

   The "<tt>gl</tt>" package prefix allows commands to pick up
   "<tt>gl::symbolic-objects</tt>" as the name to use as a default, so that
   for example, hitting @('<Return>') will take you to that topic.  But when
   reading the sentence, for best results you should ignore package prefixes.
   So for example, you would read the sentence above as follows.

   <code>
    We call these structures symbolic-objects.
   </code><p/></li>

   <li>Inside ACL2-Doc, topic names that originally contained spaces now have
   underscores in place of the spaces.  So for example, the topic @(see
   ACL2-TUTORIAL) in the ACL2+Books Manual contains a link to the topic
   originally named as follows.<br/>

   @('|Pages Written Especially for the Tours|')<br/>

   This link shows up in the ACL2-Doc browser as:<br/>

   @('[Pages_Written_Especially_for_the_Tours]').</li>

 </ol>

 Of course, the web-based browser avoids these idiosyncrasies (see @(see
 xdoc::save)); in particular, that browser is best for ``Tours'' pages like the
 one shown above and its subtopics, in part because that way you may see
 images.  Hence the web-based browser may be more appropriate for some topics,
 and for those who have no particular preference for using Emacs to browse the
 documentation.<p/></li>

 <li>Searching using the "s" or "S" command is carried out by searching
 top-to-bottom in a hidden Emacs buffer that contains all of the
 documentation.  The topics are listed in the following order according to
 topic name:<p/>

   <ol>

   <li>All topics whose names reside in the "<tt>ACL2</tt>" package;</li>

   <li>All topics whose names reside in the "<tt>ACL2-PC</tt>" package; and,
   for the ACL2+Books Manual,</li>

   <li>All other topics, sorted by @(tsee symbol-name) and then by @(tsee
   symbol-package-name).</li>

   </ol><p/></li>

 <li>You may be queried, regarding whether you want to browse the ACL2+Books
 Manual, which is preferred, or the ACL2 User's Manual, which omits
 documentation for the books.  Both of these manuals are based on files that
 you will have if you are using a released version of ACL2 (after Version 6.3).
 But if you are using a <a href='https://github.com/acl2/acl2/'>git
 version</a>, then to use the ACL2+Books Manual you will need an extra file.
 You can build this file yourself, as described below but you may prefer to
 download it: for example, when you start ACL2-Doc, you may be given the option
 of downloading <a href='https://acl2.org/doc/rendered-doc-combined.lsp.gz'>a
 tarball for the latest ``bleeding edge'' copy</a> and extracting into
 directory @('system/doc/') of your community books directory.  Indeed, the
 system will do all this for you if you answer @('y') to that query.
 Alternatively, you can insist on a download of a ``bleeding edge'' version by
 using the `<tt>D</tt>' command.  However, if you prefer to browse the ACL2
 User's Manual (without the books), you can put the following form into your
 <tt>~/.emacs</tt> file, above the form that loads the code for ACL2-Doc (see
 above).<p/>

 @({
 (defvar *acl2-doc-manual-name* 'acl2-only)
 })

 If you prefer to build @('rendered-doc-combined.lsp') yourself, you can do so
 as follows.<p/>

 <ol>

   <li>Build ACL2:
   @({
   make
   })</li>

   <li>Build the file @('books/system/doc/rendered-doc-combined.lsp') while
   standing in the @('books/') directory, as follows.  If "<tt>acl2</tt>"
   invokes the ACL2 executable that you just built, then you may omit
   "<tt>ACL2=acl2</tt>" below; otherwise replace "<tt>acl2</tt>" by a
   suitable executable.  On a multi-core machine you may wish to use @('-j'),
   e.g., @('make -j 4 ...').
   @({
   cd books
   make doc/top.cert USE_QUICKLISP=1 ACL2=acl2
   })</li>

 </ol></li></ul>")

(defxdoc acl2-doc-summary
  :parents (documentation)
  :short "Summary of @(see acl2-doc) commands"
  :long "<p>See @(see acl2-doc) for information about the custom Emacs browser
  for viewing ACL2 @(see documentation).  In the present topic we list the
  commands with extremely abbreviated documentation: only a single line for
  each.  For even briefer summaries, you can use the standard Emacs command,
  @('Control-h m').</p>

 @({
    <Return>      acl2-doc-go!
       Go to the topic occurring at the cursor position.
    Shift-<Return>  acl2-doc-go!-new-buffer
       Go to the topic occurring at the cursor position in a new buffer.
    g             acl2-doc-go
       Go to the specified topic; performs completion.
    G             acl2-doc-go-new-buffer
       Go to the specified topic in a new buffer; performs completion.
    h             acl2-doc-help
       Go to the ACL2-Doc topic to read about how to use the ACL2-Doc browser.
    ?             acl2-doc-summary
       Go to the ACL2-Doc-summary topic for one-line summaries of commands.
    i             acl2-doc-index
       Go to the specified topic or else one containing it as a substring.
    ,             acl2-doc-index-next
       Continue to the next topic for the most recent i command.
    <             acl2-doc-index-previous
       Return to the preceding topic for the most recent i command.
    K             acl2-doc-kill-buffers
       Kill all background ACL2-Doc buffers.
    l             acl2-doc-last
       Go to the last topic visited.
    n             acl2-doc-search-next
       Find the next occurrence for the most recent search.
    p             acl2-doc-search-previous
       Find the previous occurrence for the most recent search.
    q             acl2-doc-quit
       Quit the ACL2-Doc browser.
    r             acl2-doc-return
       Return to the last topic visited, popping the stack of such topics.
    s             acl2-doc-search
       Search for the input string (with prefix arg: under a given topic).
    S             acl2-doc-re-search
       Regular-expression search (with prefix arg: under a given topic).
    t             acl2-doc-top
       Go to the top topic.
    u             acl2-doc-up
       Go to the parent of the current topic.
    w             acl2-doc-where
       Display the topic and manual name in the minibuffer.
    SPC           scroll-up
       Scroll up (same as Control-v)
    TAB           acl2-doc-tab
       Visit the next link on the current page.
    <backtab> (which often is Shift-TAB): acl2-doc-tab-back
       Visit the previous link on the current page.
    D
       Download the manual from the web; then restart ACL2-Doc.
    H             acl2-doc-history
       Visit the History buffer, with names of all visited topics in order.
    I             acl2-doc-initialize
       Restart ACL2-Doc.  With a prefix argument, choose which manual.
    /             acl2-doc-definition
    Control-t /   acl2-doc-definition
       Find an ACL2 definition (in analogy to built-in Emacs command meta-.).
    W             acl2-doc-where-definition
       Find an ACL2 definition, with default from current page's topic.
 })")

(defxdoc acl2-help
  :parents (about-acl2)
  :short "The acl2-help mailing list"
  :long "<p>You can email questions about ACL2 usage to the acl2-help mailing
 list: @('acl2-help@utlists.utexas.edu').  If you have more general questions
 about ACL2, for example, about projects completed using ACL2, you may prefer
 the acl2 mailing list, @('acl2@utlists.utexas.edu'), which tends to have wider
 distribution.</p>

 <p>The following mailing list pages include links to their archives.</p>

 <ul>

 <li>acl2-help list:<br/>
 <tt><a
 href='https://utlists.utexas.edu/sympa/info/acl2-help'>https://utlists.utexas.edu/sympa/info/acl2-help</a></tt></li>

 <li>acl2 list:<br/>
 <tt><a
 href='https://utlists.utexas.edu/sympa/info/acl2'>https://utlists.utexas.edu/sympa/info/acl2</a></tt></li>

 </ul>")

(defxdoc acl2-number-listp
  :parents (numbers lists acl2-built-ins)
  :short "Recognizer for a true list of numbers"
  :long "<p>The predicate @('acl2-number-listp') tests whether its argument is
 a true list of numbers.</p>

 @(def acl2-number-listp)")

(defxdoc acl2-numberp
  :parents (numbers acl2-built-ins)
  :short "Recognizer for numbers"
  :long "<p>@('(acl2-numberp x)') is true if and only if @('x') is a number,
 i.e., a rational or complex rational number.</p>")

(defxdoc acl2-sedan
  :parents (acl2-tutorial)
  :short "ACL2 Sedan interface"
  :long "<p>Many successful ACL2 users run in a shell under Emacs; see @(see
 emacs).  However, those not familiar with Emacs may prefer to start with an
 Eclipse-based interface initially developed by Peter Dillinger and Pete
 Manolios called the ACL2 Sedan or ``ACL2s''.</p>

 <p>ACL2 sessions in the ACL2 Sedan can utilize non-standard extensions and
 enhancements, especially geared toward new users, termination reasoning, and
 attaching rich user interfaces.  These extensions are distributed with the
 ACL2 community books in @('books/acl2s/distribution/acl2s-hooks/').  Thanks to
 Peter Dillinger, Pete Manolios, Daron Vroon, and Harsh Raju Chamarthi for
 their work on the ACL2 Sedan and for making their books available to ACL2
 users.</p>")

(defxdoc acl2-tutorial
  :parents (start-here about-acl2)
  :short "Tutorial introduction to ACL2"
  :long "<p>To learn about ACL2, read at least the following two links.</p>

 <ul>

 <li><see topic='@(url INTERESTING-APPLICATIONS)'>Industrial Applications of
 ACL2</see> (10 minutes) to help you understand what sophisticated users can
 do;</li>

 <li><see topic='@(url |A Flying Tour of ACL2|)'>A Flying Tour</see> (10
 minutes) to get an overview of the system and what skills the user must
 have.</li>

 </ul>

 <p>Alternatively, or in addition, there are @(see talks) that you can peruse,
 many of them introductory in nature.</p>

 <p>If you want to learn <i>how to use</i> ACL2, we recommend that you read a
 selection of the materials referenced below, depending on your learning style,
 and do suggested exercises.</p>

 <ul>

 <li><see topic='@(url |A Walking Tour of ACL2|)'>A Walking
 Tour</see> (1 hour) provides an overview of the theorem prover.</li>

 <li>The <a href='http://tryacl2.org'>Try ACL2</a> web site provides
 interactive lessons to get you started using ACL2.</li>

 <li>See @(see introduction-to-the-theorem-prover) (10-40 hours) for
 instruction on how to interact with the system.  Unlike the three documents
 above, this document expects you to <i>think</i>!  It cites the necessary
 background pages on programming in ACL2 and on the logic and then instructs
 you in @(see the-method), which is how expert users use ACL2.  It concludes
 with some challenge problems for the ACL2 beginner (including solutions) and
 an FAQ.  Most users will spend several hours a day for several days working
 through this material.</li>

 <li>The book <a
 href='https://www.cs.utexas.edu/users/moore/publications/acl2-books/car/index.html'>Computer-Aided
 Reasoning: An Approach</a> is worth a careful read, as you work exercises and
 learn @(see the-method).</li>

 <li><see topic='@(url ANNOTATED-ACL2-SCRIPTS)'>Annotated ACL2 Scripts and
 Demos</see> contains relatively elementary proof scripts that have been
 annotated to help train the newcomer.</li>

 <li>Many files (``books'') in the ACL2 community books (see @(see
 community-books)) are extensively annotated.</li>

 <li>An <see topic='@(url ALTERNATIVE-INTRODUCTION)'>Alternative
 Introduction</see> document, while largely subsumed by the <see topic='@(url
 INTRODUCTION-TO-THE-THEOREM-PROVER)'>Introduction to the Theorem Prover</see>
 mentioned above, still might be useful because it covers much of the tutorial
 material in a different way.</li>

 </ul>

 <p>At this point you are probably ready to use ACL2 on your own <i>small</i>
 projects.  A common mistake for beginners is to browse the documentation and
 then try to do something that is too big!  Think of a very small project and
 then simplify it!</p>

 <p>Note that ACL2 has a very supportive user network.  See the link to
 ``Mailing Lists'' on the <a
 href='https://www.cs.utexas.edu/users/moore/acl2'>ACL2 home page</a>.</p>

 <p>The topics listed below are a hodge podge, developed over time.  Although
 some of these are not mentioned above, you might find some to be useful as
 well.</p>")

(defxdoc acl2-user
  :parents (packages)
  :short "A package the ACL2 user may prefer"
  :long "<p>This package imports the standard Common Lisp symbols that ACL2
 supports and also a few symbols from package @('"ACL2"') that are commonly
 used when interacting with ACL2.  You may prefer to select this as your
 current package so as to avoid colliding with ACL2 system names.</p>

 <p>This package imports the symbols listed in
 @('*common-lisp-symbols-from-main-lisp-package*'), which contains hundreds of
 CLTL function and macro names including those supported by ACL2 such as @(tsee
 cons), @(tsee car), and @(tsee cdr).  It also imports the symbols in
 @('*acl2-exports*'), which contains a few symbols that are frequently used
 while interacting with the ACL2 system, such as @(tsee implies), @(tsee
 defthm), and @(tsee rewrite).  It imports nothing else.</p>

 <p>Thus, names such as @(tsee alistp), @(tsee member-equal), and @(tsee
 type-set), which are defined in the @('"ACL2"') package are not present
 here.  If you find yourself frequently colliding with names that are defined
 in @('"ACL2"') you might consider selecting @('"ACL2-USER"') as your
 current package (see @(see in-package)).  If you select @('"ACL2-USER"') as
 the current package, you may then simply type @(tsee member-equal) to refer to
 @('acl2-user::member-equal'), which you may define as you see fit.  Of course,
 should you desire to refer to the @('"ACL2"') version of @(tsee
 member-equal), you will have to use the @('"ACL2::"') prefix, e.g.,
 @('acl2::member-equal').</p>

 <p>If, while using @('"ACL2-USER"') as the current package, you find that
 there are symbols from @('"ACL2"') that you wish we had imported into it
 (because they are frequently used in interaction), please bring those symbols
 to our attention.  For example, should @(tsee union-theories) and @(tsee
 universal-theory) be imported?  Except for stabilizing on the ``frequently
 used'' names from @('"ACL2"'), we intend never to define a symbol whose
 @(tsee symbol-package-name) is @('"ACL2-USER"').</p>")

(defxdoc acl2p-key-checkpoints
  :parents (parallel-proof)
  :short "Key checkpoints in ACL2(p)"
  :long "<p>This @(see documentation) topic relates to the experimental
 extension of ACL2 supporting parallel execution and proof; see @(see
 parallelism).</p>

 <p>For printing output, the parallel version of the waterfall follows the
 precedent of @(tsee 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 @(see 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.</p>

 <p>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 @(see
 hints)).  As an example, take the following form, which attempts to prove a
 non-theorem:</p>

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

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

 <p>For those familiar with the ACL2 waterfall, we note 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.</p>")

(defxdoc acons
  :parents (alists acl2-built-ins)
  :short "Constructor for association lists"
  :long "<p>@('(Acons key datum alist)') equals the result of consing the pair
 @('(cons key datum)') to the front of the association list @('alist').</p>

 <p>@('(Acons key datum alist)') has a @(see guard) of @('(alistp alist)').
 @('Acons') is a Common Lisp function.  See any Common Lisp documentation for
 more information.</p>

 @(def acons)")

(defxdoc active-runep
  :parents (theories)
  :short "Check that a @(see rune) exists and is @(see enable)d"
  :long "@({
  Example:
  (active-runep '(:rewrite left-to-right))

  General Form:
  (active-runep rune &optional strict)
 })

 <p>where @('rune') has the shape of a @(see rune).  This macro expands to an
 expression using the variables @('ens') and @('state'), and returns
 non-@('nil') when the given rune exists and is @(see enable)d (according to
 the given ``enabled structure,'' @('ens'), and the current logical @(see
 world) of the given @(tsee state)).  See @(see theory-invariant) for how this
 macro can be of use.</p>

 <p>When the optional argument is @('nil') or is omitted, then although the
 argument is required to have the shape of a @(see rune), it need not be a
 rune.  For example, if there is no rewrite rule named @('left-to-right'), then
 @('(active-runep '(:rewrite left-to-right))') will simply return @('nil').  If
 instead you'd like this call to cause an error, use a non-nil optional
 argument or, equivalently, use @(tsee active-or-non-runep).</p>")

(defxdoc active-or-non-runep
  :parents (theories)
  :short "Require a @(see rune) to exist, and check that it is @(see enable)d"
  :long "<p>This variant of @('active-runep') causes an error if its argument
  is not a @(see rune).  See @(see active-runep).</p>")

(defxdoc add-binop
  :parents (macros)
  :short "Associate a function name with a macro name"
  :long "<p>The form @('(add-binop macro macro-fn)') is an abbreviation for the
 form @('(add-macro-fn macro macro-fn t)').  See @(see add-macro-fn).</p>")

(defxdoc add-custom-keyword-hint
  :parents (events)
  :short "Add a new custom keyword hint"
  :long "@({
  Examples:
  (add-custom-keyword-hint :my-hint (my-hint-fn val ...))

  (add-custom-keyword-hint :my-hint
                           (my-hint-fn val ...)
                           :checker (my-hint-checker-fn val ...))
 })

 @({
  General Form:
  (add-custom-keyword-hint :key term1 :checker term2)
 })

 <p>where @(':key') is a @(tsee keywordp) not among the primitive keyword hints
 listed in @('*hint-keywords*'), the @(':checker') argument is optional, and
 @('term1') and (if supplied) @('term2') are terms with certain free-variable
 and signature restrictions described below.  Henceforth, @(':key') is treated
 as a custom keyword hint, e.g., the user can employ @(':key') in hints to
 @(tsee defthm), such as:</p>

 @({
  (defthm name ...
    :hints (("Subgoal *1/1'" ... :key val ...))).
 })

 <p>Custom keyword hints are complicated.  To use them you must understand
 @(tsee state), multiple values (e.g., @(tsee mv) and @(tsee mv-let)), ACL2's
 notion of error triples (see @(see programming-with-state)), how to generate
 ``soft'' errors with @(tsee er), how to use @(tsee fmt)-strings to control
 output, how to use computed hints (see @(see computed-hints)) and some aspects
 of ACL2's internal event processing.  Furthermore, it is possible to implement
 a custom keyword hint that can make an event non-reproducible!  So we
 recommend that these hints be developed by ACL2 experts.  Basically the custom
 keyword feature allows the implementors and other experts to extend the hint
 facility without modifying the ACL2 sources.</p>

 <p>@('Term1') is called the ``generator'' term and @('term2') is called the
 ``checker'' term of the custom keyword hint @(':key').  Together they specify
 the semantics of the new custom keyword hint @(':key').  Roughly speaking,
 when a custom keyword hint is supplied by the user, as in</p>

 @({
  (defthm name ...
    :hints (("Subgoal *1/1'" ... :my-hint val ...))).
 })

 <p>the checker term is evaluated on @('val') to check that @('val') is of the
 expected shape.  Provided @('val') passes the check, the generator term is
 used to compute a standard hint.  Like computed hints, the generator of a
 custom keyword hint is allowed to inspect the actual @(see clause) on which it
 is being fired.  Indeed, it is allowed to inspect the entire list of hints
 (standard and custom) supplied for that clause.  Thus, in the most general
 case, a custom keyword hint is just a very special kind of computed hint.</p>

 <p>The generator, @('term1'), must have no free variables other than:</p>

 @({
  (val keyword-alist
   id clause world stable-under-simplificationp
   hist pspv ctx state).
 })

 <p>Moreover, either @('term1') must evaluate to a single non-@(see stobj)
 value, or else it must be single-threaded in @('state') and have the standard
 @(see error-triple) output signature, @('(mv * * state)').</p>

 <p>The restrictions on the checker, @('term2'), are that it be single-threaded
 in @('state'), have the standard @(see error-triple) output signature, @('(mv * *
 state)'), and have no free variables other than:</p>

 @({
  (val world ctx state).
 })

 <p>For examples, see the community books directory @('books/hints/'), in
 particular @('basic-tests.lisp').</p>

 <p>To delete a previously added custom keyword hint, see @(see
 remove-custom-keyword-hint).</p>

 <p>The community book @('hints/merge-hint.lisp') can be useful in writing
 custom keyword hints.  See the examples near the of the file.</p>

 <p>Note: This is an event!  It does not print the usual event @(see summary)
 but nevertheless changes the ACL2 logical @(see world) and is so
 recorded.</p>")

(defxdoc add-default-hints
  :parents (default-hints)
  :short "Add to the default hints"
  :long "@({
  Examples:
  (add-default-hints '((computed-hint-1 clause)
                       (computed-hint-2 clause
                                        stable-under-simplificationp)))
  (add-default-hints '((computed-hint-3 id clause world))
                     :at-end t)
 })

 <p>Note: This is an event!  It does not print the usual event @(see summary)
 but nevertheless changes the ACL2 logical @(see world) and is so recorded.  It
 is @(tsee local) to the book or @(tsee encapsulate) form in which it
 occurs (see @(see add-default-hints!) for a corresponding non-@(tsee local)
 event).</p>

 @({
  General Forms:
  (add-default-hints lst)
  (add-default-hints lst :at-end flg)
 })

 <p>where @('lst') is a list.  Generally speaking, the elements of @('lst')
 should be suitable for use as @(tsee computed-hints).</p>

 <p>This event is completely analogous to @(tsee set-default-hints), the
 difference being that @('add-default-hints') appends the indicated hints to
 the front of the list of default hints, so that they are tried first &mdash;
 or, if @('flg') is supplied and evaluates to other than @('nil'), at the end
 of the list, so that they are tried last &mdash; rather than <b>replacing</b>
 the default hints with the indicated hints.  Each new hint is thus considered
 after each existing hint when both are applied to the same goal.  Also See
 @(see set-default-hints), see @(see remove-default-hints), and see @(see
 default-hints).</p>

 <p>Finally, note that the effects of @('set-default-hints'), @(tsee
 add-default-hints), and @(tsee remove-default-hints) are @(tsee local) to the
 book in which they appear.  Thus, users who include a book with such forms
 will not have their default hints affected by such forms.  In order to export
 the effect of setting the default hints, use @(tsee set-default-hints!),
 @(tsee add-default-hints!), or @(tsee remove-default-hints!).</p>

 <p>For a related feature, which however is only for advanced system builders,
 see @(see override-hints).</p>")

(defxdoc add-default-hints!
  :parents (default-hints)
  :short "Add to the default hints non-@(tsee local)ly"
  :long "<p>Please see @(see add-default-hints), which is the same as
 @('add-default-hints!')  except that the latter is not @(tsee local) to the
 @(tsee encapsulate) or the book in which it occurs.  Probably @(see
 add-default-hints) is to be preferred unless you have a good reason for
 wanting to export the effect of this event outside the enclosing @(tsee
 encapsulate) or book.</p>")

(defxdoc add-dive-into-macro
  :parents (dive-into-macros-table)
  :short "Associate @(see proof-builder) diving function with macro name"
  :long "@({
  Examples:
  (add-dive-into-macro cat expand-address-cat)
 })

 <p>This feature is used so that the interactive @(see proof-builder)'s @('DV')
 command and numeric diving commands (e.g., @('3')) will dive properly into
 subterms.  Please see @(see dive-into-macros-table).</p>")

(defxdoc add-global-stobj
  :parents (events stobj)
  :short "Add a global @(see stobj) with a given name"
  :long "<p>See @(see stobj) for background on stobjs, and see @(see defstobj)
 and @(see defabsstobj) for further background.</p>

 <p>We start with the General Form and an Example Form, which are followed by
 discussions of global stobjs and the effect of this utility.</p>

 @({
 General Form:
 (add-global-stobj x state)
 })

 <p>where @('x') evaluates to the name of a stobj that does not already have a
 global value, either because it was introduced by @(tsee defstobj) or @(tsee
 defabsstobj) with keyword value @(':non-executable t') or because @(tsee
 remove-global-stobj) was previously applied to that name.</p>

 @({
 Example Form:
 (add-global-stobj 'st state) ; st non-global from defstobj or defabsstobj
 })

 <p>By default, @('defstobj') and @('defabsstobj') create a &ldquo;live&rdquo;,
 mutable object for the given name that can be referenced at the top level,
 which we call a &ldquo;global&rdquo; stobj.  This is illustrated by the
 following log.</p>

 @({
 ACL2 !>(defstobj st fld)

 Summary
 Form:  ( DEFSTOBJ ST ...)
 Rules: NIL
 Time:  0.02 seconds (prove: 0.00, print: 0.00, other: 0.02)
  ST
 ACL2 !>st ; global stobj for the name, ST
 <st>
 ACL2 !>(fld st)
 NIL
 ACL2 !>(update-fld 3 st)
 <st>
 ACL2 !>(fld st)
 3
 ACL2 !>
 })

 <p>However, the following log shows that we can introduce a stobj without
 creating a global stobj, by using the keyword value @(':non-executable
 t').</p>

 @({
 ACL2 !>(defstobj st2 fld2 :non-executable t)

 Summary
 Form:  ( DEFSTOBJ ST2 ...)
 Rules: NIL
 Time:  0.02 seconds (prove: 0.00, print: 0.00, other: 0.02)
  ST2
 ACL2 !>(fld2 st2)


 ACL2 Error [Evaluation] in TOP-LEVEL:  Unbound var ST2.  Note that
 ST2 is a non-executable stobj.

 ACL2 !>
 })

 <p>The function @('add-global-stobj') creates a global stobj for a given stobj
 name when one does not already exist.  Let's continue the log started
 immediately above.</p>

 @({
 ACL2 !>(add-global-stobj 'st2 state)
  ST2
 ACL2 !>(fld2 st2)
 NIL
 ACL2 !>(update-fld2 3 st2)
 <st2>
 ACL2 !>(fld2 st2)
 3
 ACL2 !>
 })

 <p>The function @('remove-global-stobj') removes the indicated global stobj.
 We continue the log above.</p>

 @({
 ACL2 !>(remove-global-stobj 'st2 state)
  ST2
 ACL2 !>(fld2 st2)


 ACL2 Error [Evaluation] in TOP-LEVEL:  Unbound var ST2.  Note that
 ST2 is a non-executable stobj.

 ACL2 !>
 })

 <p>If we remove a global stobj, as shown just above, and then add the
 corresponding global stobj, we get a fresh copy of that stobj; all previous
 updates are discarded.</p>

 @({
 ACL2 !>(add-global-stobj 'st2 state)
  ST2
 ACL2 !>(fld2 st2)
 NIL
 ACL2 !>
 })")

(defxdoc add-include-book-dir
  :parents (books-reference)
  :short "Link keyword for @(':dir') argument of @(tsee ld) and @(tsee
include-book)"
  :long "@({
 Example Forms:

 ; For (include-book "foo" :dir :smith), prepend to "foo" the absolute
 ; directory pathname "/u/smith/":
 (add-include-book-dir :smith "/u/smith/")

 ; For (include-book "bar" :dir :util), prepend to "bar" the absolute
 ; directory pathname corresponding to the interpretation of "utilities/"
 ; with respect to the current connected-book-directory (cbd):
 (add-include-book-dir :util "utilities")

 ; For (include-book "lib/floor-mod/top" :dir :arith), prepend to
 ; "lib/floor-mod/top" the string "<dir>/arithmetic-5/" where "<dir>"
 ; is the community books directory pathname string:
 (add-include-book-dir :arith (:system . "arithmetic-5"))
 })

 <p>Note: This is an event!  It does not print the usual event @(see summary)
 but nevertheless changes the ACL2 logical @(see world) and is so recorded.  It
 is @(tsee local) to the book or @(tsee encapsulate) form in which it occurs.
 See @(tsee add-include-book-dir!) for a corresponding non-@(tsee local)
 event.</p>

 @({
  General Form:
  (add-include-book-dir kwd dir)
 })

 <p>where @('kwd') is a @(tsee keywordp) and @('dir') represents a directory:
 either a relative or absolute @(see pathname) string or a @(see sysfile).  If
 the final '@('/')' is missing for the resulting directory, ACL2 will add it
 for you.  The effect of this event is to modify the meaning of the @(':dir')
 keyword argument of @(tsee include-book) and @(tsee ld) as indicated by the
 examples above, that is, by associating the indicated directory with the
 indicated keyword for purposes of the @(':dir') argument.  By the ``indicated
 directory'' we mean, when a relative pathname is supplied, the directory
 relative to the current connected book directory; see @(see cbd).  See @(see
 delete-include-book-dir) for how to undo this effect.</p>

 <p>For a keyword already associated with a directory string by a previous
 invocation of @('add-include-book-dir') or @(tsee add-include-book-dir!), it
 is illegal to associate a different directory string until removing the
 existing association; see @(see delete-include-book-dir) (and see @(see
 delete-include-book-dir!) if the existing association was made by @(tsee
 add-include-book-dir!).  If however the new directory string is identical with
 the existing one, which was already assigned by @('add-include-book-dir'),
 then the new call of @('add-include-book-dir') will be redundant (see @(see
 redundant-events)).</p>

 <p>See @(tsee project-dir-alist) for another way to associate keywords with
 directory names, to take place only at the time ACL2 starts up.  Note that a
 keyword bound in the @('project-dir-alist') may also be bound by
 @('add-include-book-dir'), but only if both bindings are to the same
 directory.</p>

 <p>The keyword @(':system') can never be redefined.  It will always point to
 the absolute pathname of the @(see community-books) directory, which by
 default is the subdirectory @('"books/"') of the directory where the ACL2
 executable was built (see @(see include-book), in particular the discussion
 there of ``Books Directory'').</p>

 <p>This macro generates a @(tsee table) event that updates the @(tsee
 acl2-defaults-table) and thus is automatically @(see local) to the book or
 @(tsee encapsulate) event in which it occurs (and, it is thus illegal to call
 @('add-include-book-dir') in an explicitly @(tsee local) context).  See @(tsee
 add-include-book-dir!) for a corresponding non-@(tsee local) event.</p>

 <p>As with @(tsee add-include-book-dir!), direct table updates are disallowed;
 you must use @('add-include-book-dir') to add to the @('acl2-defaults-table')
 and @(tsee delete-include-book-dir) to remove from it.</p>")

(defxdoc add-include-book-dir!
  :parents (books-reference)
  :short "Non-@(tsee local)ly link keyword for @(':dir') argument of @(tsee ld)
and @(tsee include-book)"
  :long "<p>This topic assumes familiarity with @(see add-include-book-dir),
 which has completely analogous syntax and semantics, except that
 @('add-include-book-dir!') is not @(tsee local) to the @(tsee encapsulate) or
 the book in which it occurs.  Probably @(tsee add-include-book-dir) is to be
 preferred unless you have a good reason for wanting to export the effect of
 this event outside the enclosing @(tsee encapsulate) or book.</p>

 <p>Note: This is an event!  It does not print the usual event @(see summary)
 but nevertheless changes the ACL2 logical @(see world) and is so recorded.</p>

 <p>This macro is essentially a @(tsee table) event that updates the table
 @('include-book-dir!-table'), which associates keywords with absolute
 pathnames.  However, as with @(tsee add-include-book-dir), direct table
 updates are disallowed; you must use @('add-include-book-dir!') to add to the
 table and @(tsee delete-include-book-dir!) to remove from the table.</p>

 <p>See @(tsee project-dir-alist) for another way to associate keywords with
 directory names, to take place only at the time ACL2 starts up.  Note that a
 keyword bound in the @('project-dir-alist') may also be bound by
 @('add-include-book-dir!'), but only if both bindings are to the same
 directory.</p>

 <p>It is illegal to call @('add-include-book-dir!') in a @(tsee local)
 context.  (If you are tempted to do that, consider using @(tsee
 add-include-book-dir) instead.)  To understand this restriction, imagine a
 book that contains the following sequence of @(see events).</p>

 @({
 (add-include-book-dir! :my-dir "path/to/BAD/dir")
 (local (delete-include-book-dir! :my-dir))
 (local (add-include-book-dir! :my-dir "path/to/GOOD/dir"))
 (include-book "foo" :dir :my-dir)
 (defthm f-def
   (equal (f x) x))
 })

 <p>During the first (proof) pass of @(tsee certify-book), the book
 @('path/to/GOOD/dir/foo.lisp') will be included.  But on the second pass, the
 book @('path/to/BAD/dir/foo.lisp') will be included.  Now imagine that the
 ``good'' version contains the event @('(defun f (x) x)') but the ``bad''
 version instead contains the event @('(defun f (x) (not x))').  Then we can
 easily prove @('nil') from the theorem @('f-def')!  Although it is likely that
 @(see book-hash) values could catch this error at @(tsee include-book) time,
 we prefer not to rely on these for soundness.</p>")

(defxdoc add-invisible-fns
  :parents (loop-stopper)
  :short "Make some unary functions invisible to the @(see loop-stopper)
 algorithm"
  :long "@({
  Examples:
  (add-invisible-fns binary-+ unary-- foo)
  (add-invisible-fns + unary-- foo)
 })

 <p>Each of the @(see events) above makes unary functions @(tsee unary--) and
 @('foo') ``invisible'' for the purposes of applying permutative @(':')@(tsee
 rewrite) rules to @(tsee binary-+) trees.  Thus, @('arg') and @('(unary--
 arg)') will be given the same weight and will be permuted so as to be
 adjacent.</p>

 @({
  General Form:
  (add-invisible-fns top-fn unary-fn1 ... unary-fnk)
 })

 <p>where @('top-fn') is a function symbol and the @('unary-fni') are unary
 function symbols, or more generally, these are all macro aliases for such
 function symbols (see @(see macro-aliases-table)).</p>

 <p>For more information see @(see invisible-fns-table).  Also see @(see
 set-invisible-fns-table), which explains how to set the entire table in a
 single event, and see @(see remove-invisible-fns).</p>")

(defxdoc add-macro-alias
  :parents (macros)
  :short "Associate a function name with a macro name"
  :long "@({
  Example:
  (add-macro-alias append binary-append)
 })

 <p>This example associates the function symbol @(tsee binary-append) with the
 macro name @(tsee append).  As a result, the name @(tsee append) may be used
 as a runic designator (see @(see theories)) by the various theory functions.
 See @(see add-macro-fn) and @(see add-binop) for extensions of this utility
 that also affect printing.</p>

 @({
  General Form:
  (add-macro-alias macro-name sym)
 })

 <p>where @('macro-name') is a macro name and @('sym') is a symbol.  If
 @('sym') is a function symbol, then this event establishes @('macro-name') as
 a <i>macro-alias</i> for @('sym') by associating @('macro-name') with @('sym')
 in the @(see table), @('macro-aliases-table'); see @(see macro-aliases-table)
 for detailed discussion.  In particular, that discussion explains the use of
 macro-aliases to allow a macro name as the second argument of
 @('add-macro-alias'), as in the example below.</p>

 @({
 (defun fn (x) x)
 (defmacro mac1 (x) (fn x))
 (defmacro mac2 (x) (list 'mac1 x))
 (add-macro-alias mac1 fn); or (table macro-aliases-table 'mac1 'fn)

 ; The following is equivalent to (add-macro-alias mac2 fn), since
 ; mac1 is a macro-alias for fn by virtue of the preceding event.
 ; Note that the form (table macro-aliases-table 'mac2 'mac1)
 ; would not suffice here; that is, the in-theory event below would cause an
 ; error, because mac1 is not a function symbol.
 (add-macro-alias mac2 mac1)

 ; Success:
 (in-theory (disable mac2))
 })

 <p>Also see @(see macro-aliases-table) and also see @(see
 remove-macro-alias).</p>")

(defxdoc add-macro-fn
  :parents (macros)
  :short "Associate a function name with a macro name"
  :long "@({
  Examples:
  (add-macro-fn append binary-append)
  (add-macro-fn append binary-append t)
 })

 <p>These examples each associate the function symbol @(tsee binary-append)
 with the macro name @(tsee append).  As a result, theory functions will
 understand that @('append') refers to @('binary-append') &mdash; see @(see
 add-macro-alias) &mdash; and moreover, proof output will be printed using
 @('append') rather than @('binary-append').  In the first case, @('(append x
 (append y z))') is printed rather than @('(append x y z)').  In the second
 case, right-associated arguments are printed flat: @('(append x y z)').  Such
 right-association is considered only for binary function symbols; otherwise
 the optional third argument is ignored.</p>

 @({
  General Forms:
  (add-macro-fn macro-name function-name)
  (add-macro-fn macro-name function-name nil) ; same as above
  (add-macro-fn macro-name function-name t)
 })

 <p>This is a convenient way to add an entry to @(tsee macro-aliases-table) and
 at the same time extend the @(tsee untrans-table).  As suggested by the
 example above, calls of a function in this table will be printed as
 corresponding calls of macros, with right-associated arguments printed flat in
 the case of a binary function symbol if the optional third argument is t.  In
 that case, for a binary function symbol @('fn') associated with macro name
 @('mac'), then a call @('(fn arg1 (fn arg2 (... (fn argk arg))))') will be
 displayed to the user as though the ``term'' were @('(mac arg1 arg2 ... argk
 arg)').  For a call @('(f a1 ... ak)') of a function symbol that is not
 binary, or the optional argument is not supplied as @('t'), then the effect is
 simply to replace @('f') by the corresponding macro symbol.  See @(see
 add-macro-alias), which is invoked on the first two arguments.  Also see @(see
 remove-macro-alias), see @(see untrans-table), and see @(see
 remove-macro-fn).</p>")

(defxdoc add-match-free-override
  :parents (free-variables)
  :short "Set @(':match-free') value to @(':once') or @(':all') in existing
  rules"
  :long "@({
  Example Forms:
  (add-match-free-override :once t)
      ; Try only the first binding of free variables when relieving hypotheses
      ; of any rule of class :rewrite, :linear, or :forward-chaining.
  (add-match-free-override :all (:rewrite foo) (:rewrite bar))
      ; For rewrite rules foo and bar, try all bindings of free variables when
      ; relieving hypotheses.
  (add-match-free-override :clear)
      ; Restore :match-free to what was originally stored for each rule (either
      ; :all or :once).
 })

 <p>As described elsewhere (see @(see free-variables)), a @(see rewrite), @(see
 linear), or @(see forward-chaining) rule may have free variables in its
 hypotheses, and ACL2 can be directed either to try all bindings
 (``@(':all')'') or just the first (``@(':once')'') when relieving a
 hypothesis, as a basis for relieving subsequent hypotheses.  This direction is
 generally provided by specifying either @(':match-free :once') or
 @(':match-free :all') in the @(':')@(tsee rule-classes) of the rule, or by
 using the most recent @(tsee set-match-free-default) event.  Also see @(see
 rule-classes).</p>

 <p>However, if a proof is going slowly, you may want to modify the behavior of
 some such rules so that they use only the first match for free variables in a
 hypothesis when relieving subsequent hypotheses, rather than backtracking and
 trying additional matches as necessary.  (But note:
 @('add-match-free-override') is not relevant for @(see type-prescription)
 rules.)  The event @('(add-match-free-override :once t)') has that effect.  Or
 at the other extreme, perhaps you want to specify all rules as @(':all') rules
 except for some specific exceptions.  Then you can execute
 @('(add-match-free-override :all t)') followed by, say,
 @('(add-match-free-override :once (:rewrite foo) (:linear bar))').</p>

 @({
  General Forms:
  (add-match-free-override :clear)
  (add-match-free-override flg t)
  (add-match-free-override flg rune1 rune2 ... runek)
 })

 <p>where @('flg') is @(':once') or @(':all') and the @('runei') are @(tsee
 rune)s.  If @(':clear') is specified then all rules will have the
 @(':all')/@(':once') behavior from when they were first stored.  The second
 general form causes all @(see rewrite) @(see linear), and @(see
 forward-chaining) rules to have the behavior specified by @('flg') (@(':all')
 or @(':once')).  Finally, the last of these, where runes are specified, is
 additive in the sense that only the indicated rules are affected; all others
 keep the behavior they had just before this event was executed (possible
 because of earlier @('add-match-free-override') events).</p>

 <p>At the conclusion of this event, ACL2 prints out the list of all
 @(':')@(tsee linear), @(':')@(tsee rewrite), and @(':')@(tsee
 forward-chaining) runes whose rules contain free variables in hypotheses that
 are to be bound @(':once'), except that if there are no overrides (value
 @(':clear') was used), then @(':clear') is printed.</p>

 <p>This event only affects rules that exist at the time it is executed.
 Future rules are not affected by the override.</p>

 <p>Note: This is an event!  It does not print the usual event @(see summary)
 but nevertheless changes the ACL2 logical @(see world) and is so recorded.  It
 uses the @(tsee acl2-defaults-table), and hence its effect is @(tsee local) to
 the book or @(tsee encapsulate) form in which it occurs.</p>

 <p><i>Remarks</i></p>

 <p>Lists of the @(':')@(tsee rewrite), @(':')@(tsee linear), and @(':')@(tsee
 forward-chaining) @(see rune)s whose behavior was originally @(':once') or
 @(':all') are returned by the following forms, respectively.</p>

 @({
  (free-var-runes :once (w state))
  (free-var-runes :all  (w state))
 })

 <p>The form</p>

 @({
  (match-free-override (w state))
 })

 <p>evaluates to a pair, whose @(tsee car) is a number used by ACL2 to
 determine whether a @(see rune) is sufficiently old to be affected by the
 override, and whose @(tsee cdr) is the list of @(see rune)s whose behavior is
 specified as @(':once') by @('add-match-free-override'); except, if no runes
 have been overridden, then the keyword @(':clear') is returned.</p>")

(defxdoc add-nth-alias
  :parents (nth-aliases-table)
  :short "Associate one symbol with another for printing of @(tsee nth)/@(tsee update-nth) terms"
  :long "@({
  Example:
  (add-nth-alias st0 st)
 })

 <p>This example associates the symbol @('st0') with the symbol @('st') for
 purposes of printing certain terms of the form @('(nth n st0)') and
 @('(update-nth n val st0)').</p>

 @({
  General Form:
  (add-nth-alias alias-name name)
 })

 <p>This is a convenient way to add an entry to @(tsee nth-aliases-table).  See
 @(see nth-aliases-table) and also see @(see remove-nth-alias).</p>")

(defxdoc add-override-hints
  :parents (override-hints)
  :short "Add to the @(see override-hints)"
  :long "<p>See @(see override-hints) for a discussion of override-hints.  Here
 we describe how to extend the list of override-hints.  Note that the effects
 of @('add-override-hints') @(see events) are @(see local) to the @(see books)
 or @('encapsulate') @(see events) in which they reside; see @(see
 add-override-hints!) to avoid that restriction.  Also see @(see
 set-override-hints) to set a new list of override-hints to it, ignoring the
 present list rather than adding to it.</p>

 @({
  General Forms:
  (add-override-hints form)
  (add-override-hints form :at-end t)
  (add-override-hints form :at-end nil) ; default for :at-end
 })

 <p>where @('form') evaluates to a list of computed hint forms.  The effect of
 this event is to extend the current list of @(see override-hints) by appending
 the result of that evaluation.  The default is to append the evaluation result
 to the front of the current list of override-hints, but if @(':at-end t') is
 specified, then the evaluation result is appended to the end of the current
 list.</p>")

(defxdoc add-override-hints!
  :parents (override-hints)
  :short "Add non-@(see local)ly to the @(see override-hints)"
  :long "<p>@('Add-override-hints!') is the same as @(tsee add-override-hints),
 except that the former is not @(see local) to @(see books) or @(tsee
 encapsulate) @(see events) in which it occurs.  See @(see add-override-hints);
 also see @(see set-override-hints).</p>")

(defxdoc add-to-set
  :parents (lists symbols acl2-built-ins)
  :short "Add a symbol to a list"
  :long "@({
  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
 })

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

 <p>The @(see guard) for a call of @('add-to-set') depends on the test.  In all
 cases, the second argument must satisfy @(tsee true-listp).  If the test is
 @(tsee eql), then either the first argument must be suitable for @(tsee eql)
 (see @(see eqlablep)) or the second argument must satisfy @(tsee
 eqlable-listp).  If the test is @(tsee eq), then either the first argument
 must be a symbol or the second argument must satisfy @(tsee symbol-listp).</p>

 <p>See @(see equality-variants) for a discussion of the relation between
 @('add-to-set') and its variants:</p>

 <blockquote><p>@('(add-to-set-eq x lst)') is equivalent to @('(add-to-set x
 lst :test 'eq)');</p>

 <p>@('(add-to-set-equal x lst)') is equivalent to @('(add-to-set x lst :test
 'equal)').</p></blockquote>

 <p>In particular, reasoning about any of these primitives reduces to reasoning
 about the function @('add-to-set-equal').</p>")

(defxdoc advanced-features
  :parents (acl2-tutorial programming)
  :short "Some advanced features of ACL2"
  :long "<p>Maybe you've been using ACL2 for awhile, and you wonder if there
 are lesser-known features that you might find useful.  Then this topic is for
 you.  We present below a ``laundry list'' of some such features, with brief
 descriptions and links to @(see documentation) topics.</p>

 <p>Although the list below is long, it is not intended to be complete, and
 indeed some topics have been deliberately excluded.  Some have fallen out of
 use, perhaps for good reason, such as @(see OBDD).  Others are already likely
 to be discovered when needed, such as @(tsee GETENV$) and perhaps @(tsee
 DOUBLE-REWRITE).  Some topics are referenced by documentation for others in
 the list, such as @(tsee MBT), which is referenced by @(tsee MBE).  Some
 utilities such as @(tsee PSTACK) and @(tsee VERBOSE-PSTACK) seem too low-level
 to be worthy of inclusion below.</p>

 <p>For an extensive introduction to using the prover, which may include some
 aspects new to you, see @(see INTRODUCTION-TO-THE-THEOREM-PROVER).  A shorter
 topic contains highlights for efficient prover usage: see @(see TIPS).  Also
 see @(see ACL2-SEDAN) for an extension of ACL2 (written by others), ACL2s,
 that includes an Eclipse-based interface, more powerful and automatic
 termination reasoning, and other features.</p>

 <p>We now move on to the list.</p>

 <h3>Top-level commands and utilities:</h3>

 <ul>
 <li>See @(see A!) and see @(see P!) to abort or pop.</li>

 <li>See @(see ACL2-CUSTOMIZATION) for initial commands to run at startup.</li>

 <li>See @(see KEYWORD-COMMANDS) for how keyword commands are processed.</li>

 <li>See @(see LD) for many ways to control the top-level loop.</li>

 <li>See @(see COMPILATION) for a discussion of @('set-compiler-enabled') and
 other compiler-related utilities.</li>

 <li>For useful reader macros `@('#!')', `@('#.')', and `@('#u')', see @(see
 SHARP-BANG-READER), see @(see SHARP-DOT-READER), and see @(see
 SHARP-U-READER).</li>

 <li>To save and use an ACL2 executable, see @(see ACL2-AS-STANDALONE-PROGRAM)
 and see @(see SAVE-EXEC).</li>

 <li>For utilities related to timing, see @(see TIME$), see @(see
 WITH-PROVER-TIME-LIMIT), see @(see WITH-PROVER-STEP-LIMIT), and see @(see
 SET-PROVER-STEP-LIMIT).</li>

 <li>To query and manage the database, see @(see HISTORY) (which discusses
 many useful utilities, such as @(':')@(tsee PBT) and @(':')@(tsee PL)), and
 see @(see DEAD-EVENTS).</li>

 <li>See @(see ADD-INCLUDE-BOOK-DIR), @(see ADD-INCLUDE-BOOK-DIR!), and @(see
 PROJECT-DIR-ALIST) for linking keyword for @(':dir') argument of @(tsee LD)
 and @(tsee INCLUDE-BOOK).</li>

 <li>See @(see REBUILD) for a fast way to load a file without waiting for
 proofs.</li>

 <li>For parallel certification, see @(see BOOKS-CERTIFICATION) for use of the
 @('-j') option of `make'; also see @(see
 PROVISIONAL-CERTIFICATION).</li>

 </ul>

 <h3>Some relatively less common events</h3>

 <ul>

 <li>See @(see RESET-PREHISTORY) to reset the prehistory.</li>

 <li>See @(see ASSERT-EVENT) to assert that a given form returns a non-nil
 value.</li>

 <li>See @(see DEFATTACH) to execute constrained functions using corresponding
 attached functions.</li>

 <li>See @(see DEFUN-SK) to define a function whose body has an outermost
 quantifier.</li>

 <li>See @(see DEFCHOOSE) to define a Skolem (witnessing) function.</li>

 <li>See @(see SET-VERIFY-GUARDS-EAGERNESS) to specify when @(see guard)
 verification is tried by default.</li>

 </ul>


 <h3>Output and its control (see @(see IO) for additional information)</h3>

 <ul>

 <li>See @(see WITH-OUTPUT) to suppress or turn on specified
 output for an event.</li>

 <li>See @(see EVISC-TABLE) for support for abbreviated output.</li>

 <li>See @(see NTH-ALIASES-TABLE) for a table used to associate names for
 @(tsee NTH)/@(tsee UPDATE-NTH) printing.</li>

 <li>See @(see OUTPUT-TO-FILE) to redirect output to a file.</li>

 <li>See @(see PRINT-CONTROL) to control ACL2 printing.</li>

 <li>See @(see SET-EVISC-TUPLE) to control suppression of details when
 printing.</li>

 <li>See @(see SET-INHIBIT-OUTPUT-LST) to control output by type.</li>

 <li>See @(see SET-IPRINT) to allow abbreviated output to be read back in.</li>

 <li>See @(see SET-PRINT-BASE-RADIX) (also @(see SET-PRINT-BASE) and @(see
 SET-PRINT-RADIX)) to control the radix in which numbers are printed.</li>

 <li>See @(see SET-PRINT-CASE) to control whether symbols are printed in upper
 case or in lower case.</li>

 </ul>

 <h3>On proving termination for definitions:</h3>

 <ul>

 <li>See @(see ORDINALS) for a discussion of ordinals in ACL2.</li>

 <li>See @(see RULER-EXTENDERS) for a control on ACL2's termination and
 induction analyses.</li>

 <li>See @(see INDUCTION-COARSE-V-FINE-GRAINED) for a discussion of how a
 well-chosen setting for @(see RULER-EXTENDERS) can improve an induction
 scheme, especially for a function containing @(tsee let) and @(tsee let*)
 bindings that contain conditional recursive calls.</li>

 <li>See @(see SET-WELL-FOUNDED-RELATION) to set the default well-founded
 relation for termination analysis.</li>

 <li>See @(see ACL2-SEDAN) for a related tool that provides extra automation
 for termination proofs.</li>

 </ul>

 <h3>Proof debugging and output control:</h3>

 <ul>

 <li>See @(see ACCUMULATED-PERSISTENCE) to get statistics on which
 runes are being tried.</li>

 <li>See @(see ADD-MACRO-FN) and see @(see ADD-MACRO-ALIAS) to associate a
 function name with a macro name.</li>

 <li>See @(see BREAK-REWRITE) for how to monitor rewrite rules.</li>

 <li>See @(see DMR) for dynamic monitoring of rewriting and other prover
 activity.</li>

 <li>See @(see FORWARD-CHAINING-REPORTS) to see reports about the forward
 chaining process.</li>

 <li>See @(see GUARD-DEBUG) and @(see MEASURE-DEBUG) to generate markers to
 indicate sources of @(see guard) and termination proof obligations.</li>

 <li>See @(see PROOF-BUILDER) for support for low-level interaction.</li>

 <li>See @(see REDO-FLAT) for redo on failure of a @(tsee PROGN), @(tsee
 ENCAPSULATE), or @(tsee CERTIFY-BOOK).</li>

 <li>See @(see SET-GAG-MODE) and see @(see PSO) to abbreviate or restore proof
 output.</li>

 <li>See @(see SET-INHIBIT-OUTPUT-LST), see @(see SET-INHIBIT-WARNINGS), see
 @(see SET-INHIBIT-ER), and see @(see SET-INHIBITED-SUMMARY-TYPES) to
 inhibit various types of output.</li>

 <li>See @(see SET-RAW-PROOF-FORMAT) to make proof output display lists of
 @(see rune)s and, optionally, clausal form for goals.</li>

 <li>See @(see SET-RAW-WARNING-FORMAT) to make some warnings display in a
 ``raw'' s-expression format.</li>

 <li>See @(see SKIP-PROOFS) to skip proofs for a given form.</li>

 <li>See @(see WITH-BRR-DATA) for finding the source of a term in prover
 output.</li>

 </ul>

 <h3>Program debugging:</h3>

 <ul>

 <li>See @(see BREAK$) to cause an immediate Lisp break.</li>

 <li>See @(see BREAK-ON-ERROR) to break when encountering a hard or soft error
 caused by ACL2.</li>

 <li>See @(see DISASSEMBLE$) to disassemble a function.</li>

 <li>See @(see PRINT-GV) to print a form whose evaluation caused a guard
 violation.</li>

 <li>See @(see PROFILE) to turn on profiling for one function.</li>

 <li>See @(see TRACE$) and see @(see OPEN-TRACE-FILE) to @(see trace) function
 evaluations, possibly sending trace output to a file.</li>

 <li>See @(see WET) to evaluate a form and print a subsequent error
 trace.</li>

 </ul>

 <h3>Programming and evaluation idioms, support, utilities</h3>

 <p>(also see @(see PROGRAMMING) for more utilities, e.g., @(tsee RANDOM$)).</p>

 <ul>

 <li>See @(see ARRAYS) and See @(see DEFSTOBJ) for introductions
 to ACL2 arrays and single-threaded objects (stobjs), respectively, each of
 which provides efficient destructive operations in an applicative setting.
 Also see @(see WITH-LOCAL-STOBJ) for a way to create local stobjs.</li>

 <li>See @(see ASSERT$) to cause a hard error if the given test is false.</li>

 <li>See @(see CANONICAL-PATHNAME) to obtain the true absolute filename, with
 soft links resolved.</li>

 <li>See @(see CASE-MATCH) for a utility providing pattern matching and
 destructuring.</li>

 <li>See @(see DEFPUN) to define a tail-recursive function symbol.</li>

 <li>See @(see EC-CALL) to execute a call in the ACL2 logic instead of raw
 Lisp.</li>

 <li>See @(see ER) to print an error message and ``cause an error''.</li>

 <li>See @(see FLET) and @(see MACROLET) to provide local binding of function
 and macro names.</li>

 <li>See @(see GC$) to invoke the garbage collector.</li>

 <li>See @(see MBE) to attach code for execution.</li>

 <li>See @(see MV-LIST) to convert a @(see multiple-value) result to a
 single-value list.</li>

 <li>See @(see MV?) to return one or more values.</li>

 <li>For non-executable code, see @(see DEFUN-NX) and see @(see NON-EXEC).</li>

 <li>See @(see PROG2$) and see @(see PROGN$) to execute two or more forms and
 return the value of the last one.</li>

 <li>See @(see PROGRAMMING-WITH-STATE) for how to program using the von
 Neumannesque ACL2 @(see state) object.</li>

 <li>See @(see TOP-LEVEL) to evaluate a top-level form as a function body.</li>

 <li>See @(see WITH-GUARD-CHECKING) to suppress or enable guard-checking for a
 form.</li>

 <li>For ways to fake access to the state see @(see WORMHOLE), see @(see
 WITH-LOCAL-STATE), see @(see CW), see @(see CW!), see @(see
 PRINTING-TO-STRINGS), see @(see OBSERVATION-CW), and (dangerous!) see @(see
 WITH-LIVE-STATE).</li>

 </ul>

 <h3>Connecting with the underlying host Lisp, and doing other evil:</h3>

 <ul>

 <li>See @(see DEFTTAG) to introduce a trust tag (ttag).</li>

 <li>See @(see DEFMACRO-LAST) to define a macro that returns its last
 argument, but with side effects.</li>

 <li>See @(see PROGN!) to evaluate forms that are not necessarily @(see
 events).</li>

 <li>See @(see RETURN-LAST) to return the last argument, perhaps with side
 effects.</li>

 <li>See @(see SET-RAW-MODE) to enter or exit ``raw mode,'' a raw Lisp
 environment.</li>

 <li>See @(see SYS-CALL), @(see SYS-CALL+), and @(see SYS-CALL*) to make a
 system call to the host operating system.</li>

 </ul>

 <h3>Macros and related utilities:</h3>

 <ul>

 <li>See @(see DEFABBREV) for a convenient form of macro
 definition for simple expansions.</li>

 <li>See @(see MACRO-ARGS) for the formals list of a macro definition (see
 @(see DEFMACRO)).</li>

 <li>See @(see MAKE-EVENT) for a sort of extension of @(tsee DEFMACRO) that
 allows access to the @(see state), by evaluating (expanding) a given form and
 then evaluate the result of that expansion.</li>

 <li>See @(see TRANS), see @(see TRANS!), and see @(see TRANS1) to print the
 macroexpansion of a form.</li>

 </ul>

 <h3>Additional capabilities:</h3>

 <ul>

 <li>See @(see HONS-AND-MEMOIZATION) for a discussion of the @(see
 hons-enabled) features providing hash cons, function memoization, and
 applicative hash tables.  In particular, see @(see MEMOIZE) for efficient
 function memoization and see @(see PROFILE) for profiling.</li>

 <li>See @(see REAL) for ACL2(r), which supports the real numbers.</li>

 <li>See @(see PARALLELISM) for ACL2(p), which supports parallel evaluation
 and proof.</li>

 </ul>

 <h3>Database control and query:</h3>

 <ul>

 <li>See @(see DISABLEDP) to determine whether a given name or
 rune is disabled.</li>

 <li>For redefinition support see @(see REDEF), see @(see REDEF!), see @(see
 REDEF+), see @(see REDEF-), and see @(see REDEFINED-NAMES).</li>

 <li>See @(see TABLE) for user-managed tables.</li>

 <li>See @(see GUARD-FORMULA-UTILITIES) for how to view a guard proof
 obligation without doing the proof.</li>

 </ul>

 <h3>Prover control</h3>

 <ul>

 <li>For congruence-based reasoning see @(see DEFCONG), see @(see
 CONGRUENCE), see @(see EQUIVALENCE), see @(see DEFEQUIV), and see @(see
 DEFREFINEMENT).</li>

 <li>For meta rules and @(see clause) processors see @(see META), see @(see
 DEFEVALUATOR), see @(see CLAUSE-PROCESSOR), see @(see
 DEFINE-TRUSTED-CLAUSE-PROCESSOR) (for connecting with external tools, such as
 SAT solvers), and See @(see EXTENDED-METAFUNCTIONS) (for @(see state) and
 context-sensitive metafunctions).</li>

 <li>For theory control, see @(see THEORIES) for detailed information, but in
 particular see @(see DEFTHEORY), see @(see THEORY-FUNCTIONS), see @(see
 IN-ARITHMETIC-THEORY) (and see @(see NON-LINEAR-ARITHMETIC)), and see @(see
 THEORY-INVARIANT).</li>

 <li>See @(see HINTS) for a complete list of prover hints, including some of
 the more obscure ones such as @(':restrict'), @(':')@(tsee clause-processor),
 @(':nonlinearp'), @(':backchain-limit-rw'), @(':reorder'), and
 @(':backtrack').  Also see @(see HINTS-AND-THE-WATERFALL) for an explanation
 of how hints interact with the ACL2 proof process.  For other topics related
 to hints, see @(see OVERRIDE-HINTS), see @(see ADD-CUSTOM-KEYWORD-HINT), see
 @(see DEFAULT-HINTS), and see @(see COMPUTED-HINTS) and @(see
 USING-COMPUTED-HINTS).</li>

 <li>See @(see BIND-FREE) to bind @(see free-variables) of a @(see rewrite) or
 @(see linear) rule.</li>

 <li>See @(see CASE-SPLIT) for a utility like @(tsee FORCE) that immediately
 splits the top-level goal on the indicated hypothesis.</li>

 <li>See @(see CASE-SPLIT-LIMITATIONS) for a way to the number of cases
 produced at once</li>

 <li>See @(see DEFAULT-BACKCHAIN-LIMIT) to specify the backchain limit for a
 rule.</li>

 <li>See @(see FORCE) for an identity function used to force a hypothesis.</li>

 <li>See @(see OTF-FLG) for a way to push more than one initial subgoal for
 induction.</li>

 <li>See @(see RULE-CLASSES) to add various kinds of rules to the database,
 including more unusual sorts such as @(':')@(tsee built-in-clause) rules and
 @(':')@(tsee induction) rules.</li>

 <li>See @(see SET-BACKCHAIN-LIMIT) to set the backchain-limit used by the
 type-set and rewriting mechanisms.</li>

 <li>See @(see SET-BODY) to set an alternate definition body for @(':expand')
 @(see hints).</li>

 <li>See @(see SET-REWRITE-STACK-LIMIT) to set the @(see rewrite) stack depth
 used by the rewriter.</li>

 <li>See @(see SYNTAXP) to attach a heuristic filter on a @(':')@(tsee
 rewrite), @(':')@(tsee meta), or @(':')@(tsee linear) rule.</li>

 </ul>

 ")

(defxdoc alist-keys-subsetp
  :parents (alists acl2-built-ins)
  :short "Check that all keys of the alist belong to a given set"
  :long "<p>The call @('(alist-keys-subsetp alist keys)') returns @('t') when
 each key of the given alist belongs to the given list of keys; else it returns
 @('nil').  This is Boolean-equivalent to @('(subsetp-eq (strip-cars alist)
 keys)'), but it avoids consing up the keys of @('alist').</p>")

(defxdoc alist-to-doublets
  :parents (alists acl2-built-ins)
  :short "Convert an alist to a list of two-element lists"
  :long "<p>The call @(call alist-to-doublets) returns the result of replacing
 each pair @('(x . y)') in the given alist by the two-element list @('(x y)').
 The order is preserved, i.e., the following is a theorem.</p>

 @({
 (implies (and (natp i) (< i (len alist)))
          (equal (nth i (alist-to-doublets alist))
                 (let ((pair (nth i alist)))
                   (list (car pair) (cdr pair)))))
 })")

(defxdoc alistp
  :parents (alists acl2-built-ins)
  :short "Recognizer for association lists"
  :long "<p>@('(alistp x)') is true if and only if @('x') is a list of @(tsee
 cons) pairs.</p>

 <p>@('(alistp x)') has a @(see guard) of @('t').</p>

 @(def alistp)")

(defxdoc alists
  :parents (programming)
  :short "Operations on association lists, which bind keys to values.")

(defxdoc allegro-cl
  :parents (obtaining-common-lisp)
  :short "Allegro Common Lisp as a host for ACL2"
  :long "<p><a href='https://franz.com/products/allegro-common-lisp/'>Allegro
 Common Lisp</a> (Allegro CL) is one of the Common Lisp implementations upon
 which an ACL2 executable can be built (see @(see obtaining-common-lisp)).  But
 here, we discuss a concern.</p>

 <p>Although testing is ongoing for ACL2 built upon Allegro CL, the version
 used has been Allegro CL 10.1 since 2017.  What's more, in September 2025, for
 an ACL2 executable built with host Lisp Allegro CL, the use of &ldquo;@('make
 regression')&rdquo; resulted in four books (in the @(see community-books))
 that failed to certify.  We discuss those failures in the
 &ldquo;<b>Details</b>&rdquo; section below.  These failures may suggest that
 Allegro CL, at least for its Version 10.1, does not correctly support the
 Common Lisp language, or at least there is problematic ACL2 code specific to
 Allegro CL.  In practice we don't expect a lot of problems when using ACL2
 built on Allegro CL.  However, since Allegro CL is relatively slow compared to
 several other Common Lisp implementations that can host ACL2 &mdash; SBCL,
 CCL, LispWorks, and GCL &mdash; those failures suggest that Allegro CL might
 not be a good choice for ACL2 users.</p>

 <h3>Details</h3>

 <p>Here are details regarding the four certification failures under
 @('books/') that are referenced above.  <b>These details are quite technical
 and probably only of interest to system implementors.</b></p>

 <ul>

 <li>@('kestrel/c/syntax/validator.lisp')<p/>

 <p>The following error from the corresponding @('validator.cert.out') file is
 very surprising, since the @(tsee defrec) form for
 @('ACL2::CLAUSE-PROCESSOR-HINT') has a &ldquo;cheap&rdquo; flag of @('nil'),
 so the same error can be expected to show up regardless of the host Lisp
 &mdash; yet as of this writing (in September 2025) it seems not to have shown
 up for a long time, if ever.</p>

 @({
 HARD ACL2 ERROR in ACL2::RECORD-ERROR:  An attempt was made to treat
 (49683 :TYPE-PRESCRIPTION BLOCK-ITEM-TYPES) as a record of type
 ACL2::CLAUSE-PROCESSOR-HINT.
 })

 <p>There were other errors like that one as well.</p>

 <p>So for that same ACL2 version (ACL2 git hash
 fe29908c4589c1de3b41d6c98cc8bec012c7eba3), the same book and the books that
 (recursively) support it were certified using a safety-3 ACL2 executable built
 on CCL.  The book certified without any &ldquo;HARD ACL2 ERROR&rdquo;.  This
 suggests that the problem is likely restricted to runs using Allegro CL.</p>

 <p>However, that book allows some trust tags (in file @('cert.acl2') in that
 directory), so perhaps there are shenanigans that somehow exonerate the
 Allegro CL build of ACL2.  But the last failure discussed below does not
 involve trust tags.</p>

 </li>

 <li>@('kestrel/axe/examples/aes-blast.lisp')<br/>
 @('kestrel/axe/examples/aes-blast-boolean.lisp')<p/>

 <p>These two report errors (in their @('.cert.out') files) that involve using
 the @(see serialize) capability to write the @('.cert') file.  But
 @('cert.acl2') in that directory allows trust tags, which could be relevant.
 Note that serialize errors may be very difficult to debug.</p>

 <p>A second certification was tried on the second of these (picked
 arbitrarily) in case this was just a weird glitch.  However, a similar error
 occurred (though with a slightly different backtrace).</p>

 </li>

 <li>@('projects/aleo/vm/circuits/axe/blake2s-proof2.lisp')<p/>

 <p>This one shows a backtrace that includes the following form.</p>

 @({
 (RATIONALP 8444461749428370424248824938781546531375899335154063827935233455916872368129)
 })

 <p>That shouldn't cause an error, but apparently it did.  Maybe the image was
 already corrupted.  Submitting that form in a fresh session produced no
 error.</p>

 <p>As with the first example, a safety-3 CCL-based certification (of this book
 and all supporting books, recursively) produced no errors.  But unlike the
 first example, this book does not allow trust tags.  This example thus
 provides strong evidence that Allegro CL is not a great choice for hosting
 ACL2.</p>

 </li>

 </ul>")

(defxdoc allocate-fixnum-range
  :parents (numbers acl2-built-ins)
  :short "Set aside fixnums in GCL"
  :long "<p>@('(Allocate-fixnum-range fixnum-lo fixnum-hi)') causes Gnu Common
 Lisp (GCL), versions preceding 2.7, 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 (again, for versions preceding 2.7) 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').</p>

 <p>When this function is executed in a Lisp implementation other than a GCL
 version preceding 2.7, it has no side effect other than to print a message.
 This function always returns @('nil').</p>

 <p>In GCL versions starting with 2.7.0, allocation for the table would
 generally be a no-op other than to waste space, which is why
 @('allocate-fixnum-range') is a no-op for those versions.</p>")

(defxdoc alpha-char-p
  :parents (characters acl2-built-ins)
  :short "Recognizer for alphabetic characters"
  :long "<p>@('(Alpha-char-p x)') is true for a character @('x') if and only if
 @('x') is alphabetic, i.e., one of the @(see characters) @('#\a'), @('#\b'),
 ..., @('#\z'), @('#\A'), @('#\B'), ..., @('#\Z').</p>

 <p>The @(see guard) for @('alpha-char-p') states that its argument is a
 character.</p>

 <p>@('Alpha-char-p') is a Common Lisp function.  See any Common Lisp
 documentation for more information.  Note that the value returned may depend
 on the host Lisp; see @(see soundness), specifically Example 1 in the Section,
 &ldquo;Examples of divergence among Lisp implementations&rdquo;.</p>

 @(def alpha-char-p)")

(defxdoc alphorder
  :parents (<< acl2-built-ins)
  :short "Total order on atoms"
  :long "<p>@('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.</p>

 <ul>

 <li>Antisymmetry: @('XrY & YrX -> X=Y')</li>

 <li>Transitivity: @('XrY & YrZ -> XrZ')</li>

 <li>Trichotomy: @('XrY v YrX')</li>

 </ul>

 <p>Also see @(see lexorder), which extends @('alphorder') to all objects.</p>

 <p>@('(Alphorder x y)') has a guard of @('(and (atom x) (atom y))').</p>

 <p>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.</p>

 @(def alphorder)")

(defxdoc alternative-introduction
  :parents (acl2-tutorial)
  :short "Introduction to ACL2"
  :long "<p>This section contains introductory material on ACL2 including what
 ACL2 is, how to get started using the system, how to read the output, and
 other introductory topics.  It was written almost entirely by Bill Young of
 Computational Logic, Inc.</p>

 <p>You might also find CLI Technical Report 101 helpful, especially if you are
 familiar with Nqthm.  If you would like more familiarity with Nqthm, we
 suggest CLI Technical Report 100.</p>

 <p><i>OVERVIEW</i></p>

 <p>ACL2 is an automated reasoning system developed (for the first 9 years) at
 Computational Logic, Inc. and (from January, 1997) at the University of Texas
 at Austin.  It is the successor to the Nqthm (or Boyer-Moore) logic and proof
 system and its Pc-Nqthm interactive enhancement.  The acronym ACL2 actually
 stands for ``A Computational Logic for Applicative Common Lisp''.  This title
 suggests several distinct but related aspects of ACL2.</p>

 <p>We assume that readers of the ACL2 @(see documentation) have at least a
 very slight familiarity with some Lisp-like language.  We will address the
 issue of prerequisites further, in ``ABOUT THIS TUTORIAL'' below.</p>

 <p>As a <b>logic</b>, ACL2 is a formal system with rigorously defined syntax
 and semantics.  In mathematical parlance, the ACL2 logic is a first-order
 logic of total recursive functions providing mathematical induction on the
 ordinals up to epsilon-0 and two extension principles: one for recursive
 definition and one for constrained introduction of new function symbols, here
 called encapsulation.  The syntax of ACL2 is that of Common Lisp; ACL2
 specifications are ``also'' Common Lisp programs in a way that we will make
 clear later.  In less formal language, the ACL2 logic is an integrated
 collection of rules for defining (or axiomatizing) recursive functions,
 stating properties of those functions, and rigorously establishing those
 properties.  Each of these activities is mechanically supported.</p>

 <p>As a <b>specification language</b>, ACL2 supports modeling of systems of
 various kinds.  An ACL2 function can equally be used to express purely formal
 relationships among mathematical entities, to describe algorithms, or to
 capture the intended behavior of digital systems.  For digital systems, an
 ACL2 specification is a mathematical <b>model</b> that is intended to
 formalize relevant aspects of system behavior.  Just as physics allows us to
 model the behavior of continuous physical systems, ACL2 allows us to model
 digital systems, including many with physical realizations such as computer
 hardware.  As early as the 1930's Church, Kleene, Turing and others
 established that recursive functions provide an expressive formalism for
 modeling digital computation.  Digital computation should be understood in a
 broad sense, covering a wide variety of activities including almost any
 systematic or algorithmic activity, or activity that can be reasonably
 approximated in that way.  This ranges from the behavior of a digital circuit
 to the behavior of a programming language compiler to the behavior of a
 controller for a physical system (as long as the system can be adequately
 modeled discretely).  All of these have been modeled using ACL2 or its
 predecessor Nqthm.</p>

 <p>ACL2 is a <b>computational</b> logic in at least three distinct senses.
 First, the theory of recursive functions is often considered the mathematics
 of computation.  Church conjectured that any ``effective computation'' can be
 modeled as a recursive function.  Thus, ACL2 provides an expressive language
 for modeling digital systems.  Second, many ACL2 specifications are
 executable.  In fact, recursive functions written in ACL2 <b>are</b> Common
 Lisp functions that can be submitted to any compliant Common Lisp compiler and
 executed (in an environment where suitable ACL2-specific macros and functions
 are defined).  Third, ACL2 is computational in the sense that calculation is
 heavily integrated into the reasoning process.  Thus, an expression with
 explicit constant values but no free variables can be simplified by
 calculation rather than by complex logical manipulations.</p>

 <p>ACL2 is a powerful, automated <b>theorem prover</b> or proof checker.  This
 means that a competent user can utilize the ACL2 system to discover proofs of
 theorems stated in the ACL2 logic or to check previously discovered proofs.
 The basic deductive steps in an ACL2-checked proof are often quite large, due
 to the sophisticated combination of decision procedures, conditional
 rewriting, mathematical and structural induction, propositional
 simplification, and complex heuristics to orchestrate the interactions of
 these capabilities.  Unlike some automated proof systems, ACL2 does not
 produce a formal proof.  However, we believe that if ACL2 certifies the
 ``theoremhood'' of a given conjecture, then such a formal proof exists and,
 therefore, the theorem is valid.  The ultimate result of an ACL2 proof session
 is a collection of ``@(see events),'' possibly grouped into ``@(see books),''
 that can be replayed in ACL2.  Therefore, a proof can be independently
 validated by any ACL2 user.</p>

 <p>ACL2 may be used in purely automated mode in the shallow sense that
 conjectures are submitted to the prover and the user does not interact with
 the proof attempt (except possibly to stop it) until the proof succeeds or
 fails.  However, any non-trivial proof attempt is actually interactive, since
 successful proof ``@(see events)'' influence the subsequent behavior of the
 prover.  For example, proving a lemma may introduce a rule that subsequently
 is used automatically by the prover.  Thus, any realistic proof attempt, even
 in ``automatic'' mode, is really an interactive dialogue with the prover to
 craft a sequence of @(see events) building an appropriate theory and proof
 rules leading up to the proof of the desired result.  Also, ACL2 supports
 annotating a theorem with ``@(see hints)'' designed to guide the proof
 attempt.  By supplying appropriate @(see hints), the user can suggest proof
 strategies that the prover would not discover automatically.  There is a
 ``@(see proof-tree)'' facility (see @(see proof-tree)) that allows the user to
 @(see monitor) the progress and structure of a proof attempt in real-time.
 Exploring failed proof attempts is actually where heavy-duty ACL2 users spend
 most of their time.</p>

 <p>ACL2 can also be used in a more explicitly interactive mode.  The
 interactive @(see proof-builder) subsystem of ACL2 allows exploration of a
 proof on a fairly low level including expanding calls of selected function
 symbols, invoking specific @(see rewrite) rules, and selectively navigating
 around the proof.  This facility can be used to gain sufficient insight into
 the proof to construct an automatic version, or to generate a detailed
 interactive-style proof that can be replayed in batch mode.</p>

 <p>Because ACL2 is all of these things &mdash; computational logic,
 specification language, @(see programming) system, and theorem prover &mdash;
 it is more than the sum of its parts.  The careful integration of these
 diverse aspects has produced a versatile automated reasoning system suitable
 for building highly reliable digital systems.  In the remainder of this
 tutorial, we will illustrate some simple uses of this automated reasoning
 system.</p>

 <p><i>ABOUT THIS TUTORIAL</i></p>

 <p>ACL2 is a complex system with a vast array of features, bells and whistles.
 However, it is possible to perform productive work with the system using only
 a small portion of the available functionality.  The goals of this tutorial
 are to:</p>

 <blockquote>

 <p>familiarize the new user with the most basic features of and modes of
 interaction with ACL2;</p>

 <p>familiarize her with the form of output of the system; and</p>

 <p>work through a graduated series of examples.</p></blockquote>

 <p>The more knowledge the user brings to this system, the easier it will be to
 become proficient.  On one extreme: the <b>ideal</b> user of ACL2 is an expert
 Common Lisp programmer, has deep understanding of automated reasoning, and is
 intimately familiar with the earlier Nqthm system.  Such ideal users are
 unlikely to need this tutorial.  However, without some background knowledge,
 the beginning user is likely to become extremely confused and frustrated by
 this system.  We suggest that a new user of ACL2 should:</p>

 <blockquote>

 <p>(a) have a little familiarity with Lisp, including basic Lisp programming
 and prefix notation (a Lisp reference manual such as Guy Steele's ``Common
 Lisp: The Language'' is also helpful);</p>

 <p>(b) be convinced of the utility of formal modeling; and</p>

 <p>(c) be willing to gain familiarity with basic automated theorem proving
 topics such as rewriting and algebraic simplification.</p></blockquote>

 <p>We will not assume any deep familiarity with Nqthm (the so-called
 ``Boyer-Moore Theorem Prover''), though the book ``A Computational Logic
 Handbook'' by Boyer and Moore (Academic Press, 1988) is an extremely useful
 reference for many of the topics required to become a competent ACL2 user.
 We'll refer to it as ACLH below.</p>

 <p>As we said in the introduction, ACL2 has various facets.  For example, it
 can be used as a Common Lisp @(see programming) system to construct
 application programs.  In fact, the ACL2 system itself is a large Common Lisp
 program constructed almost entirely within ACL2.  Another use of ACL2 is as a
 specification and modeling tool.  That is the aspect we will concentrate on in
 the remainder of this tutorial.</p>

 <p><i>GETTING STARTED</i></p>

 <p>This section is an abridged version of what's available elsewhere; feel
 free to see @(see startup) for more details.</p>

 <p>How you start ACL2 will be system dependent, but you'll probably type
 something like ``acl2'' at your operating system prompt.  Consult your system
 administrator for details.</p>

 <p>When you start up ACL2, you'll probably find yourself inside the ACL2 @(see
 command) loop, as indicated by the following @(see prompt).</p>

 @({
    ACL2 !>
 })

 <p>If not, you should type @('(LP)').  See @(see lp), which has a lot more
 information about the ACL2 @(see command) loop.</p>

 <p>There are two ``modes'' for using ACL2, @(':')@(tsee logic) and
 @(':')@(tsee program).  When you begin ACL2, you will ordinarily be in the
 @(':')@(tsee logic) mode.  This means that any new function defined is not
 only executable but also is axiomatically defined in the ACL2 logic.  (See
 @(see defun-mode) and see @(see default-defun-mode).)  Roughly speaking,
 @(':')@(tsee program) mode is available for using ACL2 as a @(see programming)
 language without some of the logical burdens necessary for formal reasoning.
 In this tutorial we will assume that we always remain in @(':')@(tsee logic)
 mode and that our purpose is to write formal models of digital systems and to
 reason about them.</p>

 <p>Now, within the ACL2 @(see command) loop you can carry out various kinds of
 activities, including the following.  (We'll see examples later of many of
 these.)</p>

 <blockquote>

 <p>define new functions (see @(see defun));</p>

 <p>execute functions on concrete data;</p>

 <p>pose and attempt to prove conjectures about previously defined functions
 (see @(see defthm));</p>

 <p>query the ACL2 ``@(see world)'' or database (e.g., see @(see pe)); and</p>

 <p>numerous other things.</p></blockquote>

 <p>In addition, there is extensive on-line @(see documentation), of which this
 tutorial introduction is a part.</p>

 <p><i>INTERACTING WITH ACL2</i></p>

 <p>The standard means of interacting with ACL2 is to submit a sequence of
 forms for processing by the ACL2 system.  These forms are checked for
 syntactic and semantic acceptability and appropriately processed by the
 system.  These forms can be typed directly at the ACL2 @(see prompt).
 However, most successful ACL2 users prefer to do their work using the Emacs
 text editor, maintaining an Emacs ``working'' buffer in which forms are
 edited.  Those forms are then copied to the ACL2 interaction buffer, which is
 often the @('"*shell*"') buffer.</p>

 <p>In some cases, processing succeeds and makes some change to the ACL2
 ``logical @(see world),'' which affects the processing of subsequent forms.
 How can this processing fail?  For example, a proposed theorem will be
 rejected unless all function symbols mentioned have been previously defined.
 Also the ability of ACL2 to discover the proof of a theorem may depend on the
 user previously having proved other theorems.  Thus, the order in which forms
 are submitted to ACL2 is quite important.  Maintaining forms in an appropriate
 order in your working buffer will be helpful for re-playing the proof
 later.</p>

 <p>One of the most common @(see events) in constructing a model is introducing
 new functions.  New functions are usually introduced using the @(tsee defun)
 form; we'll encounter some exceptions later.  Proposed function definitions
 are checked to make sure that they are syntactically and semantically
 acceptable (e.g., that all mentioned functions have been previously defined)
 and, for recursive functions, that their recursive calls <b>terminate</b>.  A
 recursive function definition is guaranteed to terminate if there is some some
 ``measure'' of the arguments and a ``well-founded'' ordering such that the
 arguments to the function get smaller in each recursive call.  See @(see
 well-founded-relation-rule).</p>

 <p>For example, suppose that we need a function that will append two lists
 together.  (We already have one in the ACL2 @(tsee append) function; but
 suppose perversely that we decide to define our own.)  Suppose we submit the
 following definition (you should do so as well and study the system
 output):</p>

 @({
    (defun my-app (x y)
      (if (atom x)
          y
        (cons (car x) (my-app x y))))
 })

 <p>The system responds with the following message:</p>

 @({
    ACL2 Error in ( DEFUN MY-APP ...):  No :MEASURE was supplied with
    the definition of MY-APP.  Our heuristics for guessing one have not
    made any suggestions.  No argument of the function is tested along
    every branch and occurs as a proper subterm at the same argument
    position in every recursive call.  You must specify a :MEASURE.  See
    :DOC defun.
 })

 <p>This means that the system could not find an expression involving the
 formal parameters @('x') and @('y') that decreases under some well-founded
 order in every recursive call (there is only one such call).  It should be
 clear that there is no such measure in this case because the only recursive
 call doesn't change the arguments at all.  The definition is obviously flawed;
 if it were accepted and executed it would loop forever.  Notice that a
 definition that is rejected is not stored in the system database; there is no
 need to take any action to have it ``thrown away.''  Let's try again with the
 correct definition.  The interaction now looks like (we're also putting in the
 ACL2 @(see prompt); you don't type that):</p>

 @({
    ACL2 !>(defun my-app (x y)
             (if (atom x)
                 y
               (cons (car x) (my-app (cdr x) y))))

    The admission of MY-APP 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 observe that the
    type of MY-APP is described by the theorem
    (OR (CONSP (MY-APP X Y)) (EQUAL (MY-APP X Y) Y)).
    We used primitive type reasoning.

    Summary
    Form:  ( DEFUN MY-APP ...)
    Rules: ((:FAKE-RUNE-FOR-TYPE-SET NIL))
    Warnings:  None
    Time:  0.07 seconds (prove: 0.00, print: 0.00, other: 0.07)
    MY-APP
 })

 <p>Notice that this time the function definition was accepted.  We didn't have
 to supply a measure explicitly; the system inferred one from the form of the
 definition.  On complex functions it may be necessary to supply a measure
 explicitly.  (See @(see xargs).)</p>

 <p>The system output provides several pieces of information.</p>

 <blockquote>

 <p>The revised definition is acceptable.  The system realized that there is a
 particular measure (namely, @('(acl2-count x)')) and a well-founded relation
 (@('o<')) under which the arguments of @('my-app') get smaller in recursion.
 Actually, the theorem prover proved several theorems to admit @('my-app').
 The main one was that when @('(atom x)') is false the @('acl2-count') of
 @('(cdr x)') is less than (in the @('o<') sense) the @('acl2-count') of
 @('x').  @(tsee Acl2-count) is the most commonly used measure of the ``size``
 of an ACL2 object.  @(tsee o<) is the ordering relation on ordinals less than
 epsilon-0.  On the natural numbers it is just ordinary ``&lt;''.</p>

 <p>The observation printed about ``the type of MY-APP'' means that calls of
 the function @('my-app') will always return a value that is either a @(see
 cons) pair or is equal to the second parameter.</p>

 <p>The @(see summary) provides information about which previously introduced
 definitions and lemmas were used in this proof, about some notable things to
 watch out for (the Warnings), and about how long this event took to
 process.</p></blockquote>

 <p>Usually, it's not important to read this information.  However, it is a
 good habit to scan it briefly to see if the type information is surprising to
 you or if there are Warnings.  We'll see an example of them later.</p>

 <p>After a function is accepted, it is stored in the database and available
 for use in other function definitions or lemmas.  To see the definition of any
 function use the @(':')@(tsee pe) command (see @(see pe)).  For example,</p>

 @({
    ACL2 !>:pe my-app
     L       73:x(DEFUN MY-APP (X Y)
                        (IF (ATOM X)
                            Y (CONS (CAR X) (MY-APP (CDR X) Y))))
 })

 <p>This displays the definition along with some other relevant information.
 In this case, we know that this definition was processed in @(':')@(tsee
 logic) mode (the ``@('L')'') and was the 73rd @(see command) processed in the
 current session.</p>

 <p>We can also try out our newly defined function on some sample data.  To do
 that, just submit a form to be evaluated to ACL2.  For example,</p>

 @({
    ACL2 !>(my-app '(0 1 2) '(3 4 5))
    (0 1 2 3 4 5)
    ACL2 !>(my-app nil nil)
    NIL
    ACL2 !>
 })

 <p>Now suppose we want to prove something about the function just introduced.
 We conjecture, for example, that the length of the @(see append) of two lists
 is the sum of their lengths.  We can formulate this conjecture in the form of
 the following ACL2 @(tsee defthm) form.</p>

 @({
    (defthm my-app-length
      (equal (len (my-app x y))
             (+ (len x) (len y))))
 })

 <p>First of all, how did we know about the functions @('len') and @(tsee +),
 etc.?  The answer to that is somewhat unsatisfying &mdash; we know them from
 our past experience in using Common Lisp and ACL2.  It's hard to know that a
 function such as @('len') exists without first knowing some Common Lisp.  If
 we'd guessed that the appropriate function was called @(tsee length) (say,
 from our knowledge of Lisp) and tried @(':pe length'), we would have seen that
 @(tsee length) is defined in terms of @('len'), and we could have explored
 from there.  Luckily, you can write a lot of ACL2 functions without knowing
 too many of the primitive functions.</p>

 <p>Secondly, why don't we need some ``type'' hypotheses?  Does it make sense
 to append things that are not lists?  Well, yes.  ACL2 and Lisp are both quite
 weakly typed.  For example, inspection of the definition of @('my-app') shows
 that if @('x') is not a @(see cons) pair, then @('(my-app x y)') always
 returns @('y'), no matter what @('y') is.</p>

 <p>Thirdly, would it matter if we rewrote the lemma with the equality
 reversed, as follows?</p>

 @({
    (defthm my-app-length2
      (equal (+ (len x) (len y))
             (len (my-app x y)))).
 })

 <p>The two are <b>logically</b> equivalent, but...yes, it would make a big
 difference.  Recall our remark that a lemma is not only a ``fact'' to be
 proved; it also is used by the system to prove other later lemmas.  The
 current lemma would be stored as a @(see rewrite) rule.  (See @(see
 rule-classes).)  For a @(see rewrite) rule, a conclusion of the form @('(EQUAL
 LHS RHS)') means to replace instances of the @('LHS') by the appropriate
 instance of the @('RHS').  Presumably, it's better to @(see rewrite) @('(len
 (my-app x y))') to @('(+ (len x) (len y))') than the other way around.  The
 reason is that the system ``knows'' more about @(tsee +) than it does about
 the new function symbol @('my-app').</p>

 <p>So let's see if we can prove this lemma.  Submitting our preferred @(tsee
 defthm) to ACL2 (do it!), we get the following interaction:</p>

 @({
            --------------------------------------------------
  ACL2 !>(defthm my-app-length
    (equal (len (my-app x y))
           (+ (len x) (len y))))

  Name the formula above *1.

  Perhaps we can prove *1 by induction.  Three induction schemes are
  suggested by this conjecture.  These merge into two derived
  induction schemes.  However, one of these is flawed and so we are
  left with one viable candidate.

  We will induct according to a scheme suggested by (LEN X), while
  accommodating (MY-APP X Y).

  These suggestions were produced using the :induction rules LEN and
  MY-APP. If we let (:P X Y) denote *1 above then the induction scheme
  we'll use is
  (AND (IMPLIES (NOT (CONSP X)) (:P X Y))
       (IMPLIES (AND (CONSP X) (:P (CDR X) Y))
                (:P X Y))).
  This induction is justified by the same argument used to admit LEN.
  When applied to the goal at hand the above induction scheme produces
  two nontautological subgoals.

  Subgoal *1/2
  (IMPLIES (NOT (CONSP X))
           (EQUAL (LEN (MY-APP X Y))
                  (+ (LEN X) (LEN Y)))).

  But simplification reduces this to T, using the :definitions of FIX,
  LEN and MY-APP, the :type-prescription rule LEN, the :rewrite rule
  UNICITY-OF-0 and primitive type reasoning.

  Subgoal *1/1
  (IMPLIES (AND (CONSP X)
                (EQUAL (LEN (MY-APP (CDR X) Y))
                       (+ (LEN (CDR X)) (LEN Y))))
           (EQUAL (LEN (MY-APP X Y))
                  (+ (LEN X) (LEN Y)))).

  This simplifies, using the :definitions of LEN and MY-APP, primitive
  type reasoning and the :rewrite rules COMMUTATIVITY-OF-+ and
  CDR-CONS, to

  Subgoal *1/1'
  (IMPLIES (AND (CONSP X)
                (EQUAL (LEN (MY-APP (CDR X) Y))
                       (+ (LEN Y) (LEN (CDR X)))))
           (EQUAL (+ 1 (LEN (MY-APP (CDR X) Y)))
                  (+ (LEN Y) 1 (LEN (CDR X))))).

  But simplification reduces this to T, using linear arithmetic,
  primitive type reasoning and the :type-prescription rule LEN.

  That completes the proof of *1.

  Q.E.D.

  Summary
  Form:  ( DEFTHM MY-APP-LENGTH ...)
  Rules: ((:REWRITE UNICITY-OF-0)
          (:DEFINITION FIX)
          (:REWRITE COMMUTATIVITY-OF-+)
          (:DEFINITION LEN)
          (:REWRITE CDR-CONS)
          (:DEFINITION MY-APP)
          (:TYPE-PRESCRIPTION LEN)
          (:FAKE-RUNE-FOR-TYPE-SET NIL)
          (:FAKE-RUNE-FOR-LINEAR NIL))
  Warnings:  None
  Time:  0.30 seconds (prove: 0.13, print: 0.05, other: 0.12)
   MY-APP-LENGTH
            --------------------------------------------------
 })

 <p>Wow, it worked!  In brief, the system first tried to @(see rewrite) and
 simplify as much as possible.  Nothing changed; we know that because it said
 ``Name the formula above *1.''  Whenever the system decides to name a formula
 in this way, we know that it has run out of techniques to use other than proof
 by induction.</p>

 <p>The induction performed by ACL2 is structural or ``Noetherian'' induction.
 You don't need to know much about that except that it is induction based on
 the structure of some object.  The heuristics infer the structure of the
 object from the way the object is recursively decomposed by the functions used
 in the conjecture.  The heuristics of ACL2 are reasonably good at selecting an
 induction scheme in simple cases.  It is possible to override the heuristic
 choice by providing an @(':induction') hint (see @(see hints)).  In the case
 of the theorem above, the system inducts on the structure of @('x') as
 suggested by the decomposition of @('x') in both @('(my-app x y)') and @('(len
 x)').  In the base case, we assume that @('x') is not a @(tsee consp).  In the
 inductive case, we assume that it is a @(tsee consp) and assume that the
 conjecture holds for @('(cdr x)').</p>

 <p>There is a close connection between the analysis that goes on when a
 function like @('my-app') is accepted and when we try to prove something
 inductively about it.  That connection is spelled out well in Boyer and
 Moore's book ``A Computational Logic,'' if you'd like to look it up.  But it's
 pretty intuitive.  We accepted @('my-app') because the ``size'' of the first
 argument @('x') decreases in the recursive call.  That tells us that when we
 need to prove something inductively about @('my-app'), it's a good idea to try
 an induction on the size of the first argument.  Of course, when you have a
 theorem involving several functions, it may be necessary to concoct a more
 complicated @(see induction) schema, taking several of them into account.
 That's what's meant by ``merging'' the induction schemas.</p>

 <p>The proof involves two cases: the base case, and the inductive case.
 You'll notice that the subgoal numbers go <b>down</b> rather than up, so you
 always know how many subgoals are left to process.  The base case (@('Subgoal
 *1/2')) is handled by opening up the function definitions, simplifying, doing
 a little rewriting, and performing some reasoning based on the types of the
 arguments.  You'll often encounter references to system defined lemmas (like
 @('unicity-of-0')).  You can always look at those with @(':')@(tsee pe); but,
 in general, assume that there's a lot of simplification power under the hood
 that's not too important to understand fully.</p>

 <p>The inductive case (@('Subgoal *1/1')) is also dispatched pretty easily.
 Here we assume the conjecture true for the @(tsee cdr) of the list and try to
 prove it for the entire list.  Notice that the prover does some simplification
 and then prints out an updated version of the goal (@('Subgoal *1/1'')).
 Examining these gives you a pretty good idea of what's going on in the
 proof.</p>

 <p>Sometimes one goal is split into a number of subgoals, as happened with the
 induction above.  Sometimes after some initial processing the prover decides
 it needs to prove a subgoal by induction; this subgoal is given a name and
 pushed onto a stack of goals.  Some steps, like generalization (see ACLH), are
 not necessarily validity preserving; that is, the system may adopt a false
 subgoal while trying to prove a true one.  (Note that this is ok in the sense
 that it is not ``unsound.''  The system will fail in its attempt to establish
 the false subgoal and the main proof attempt will fail.)  As you gain facility
 with using the prover, you'll get pretty good at recognizing what to look for
 when reading a proof script.  The prover's @(see proof-tree) utility helps
 with monitoring an ongoing proof and jumping to designated locations in the
 proof (see @(see proof-tree)).  See @(see tips) for a number of useful
 pointers on using the theorem prover effectively.</p>

 <p>When the prover has successfully proved all subgoals, the proof is
 finished.  As with a @(tsee defun), a @(see summary) of the proof is printed.
 This was an extremely simple proof, needing no additional guidance.  More
 realistic examples typically require the user to look carefully at the failed
 proof log to find ways to influence the prover to do better on its next
 attempt.  This means either: proving some rules that will then be available to
 the prover, changing the global state in ways that will affect the proof, or
 providing some @(see hints) locally that will influence the prover's behavior.
 Proving this lemma (@('my-app-length')) is an example of the first.  Since
 this is a @(see rewrite) rule, whenever in a later proof an instance of the
 form @('(LEN (MY-APP X Y))') is encountered, it will be rewritten to the
 corresponding instance of @('(+ (LEN X) (LEN Y))').  Disabling the rule by
 executing the @(see command)</p>

 @({
    (in-theory (disable my-app-length)),
 })

 <p>is an example of a global change to the behavior of the prover since this
 @(see rewrite) will not be performed subsequently (unless the rule is again
 @(see enable)d).  Finally, we can add a (local) @(see disable) ``hint'' to a
 @(tsee defthm), meaning to @(see disable) the lemma only in the proof of one
 or more subgoals.  For example:</p>

 @({
    (defthm my-app-length-commutativity
      (equal (len (my-app x y))
             (len (my-app y x)))
      :hints (("Goal" :in-theory (disable my-app-length))))
 })

 <p>In this case, the hint supplied is a bad idea since the proof is much
 harder with the hint than without it.  Try it both ways.</p>

 <p>By the way, to undo the previous event use @(':u') (see @(see u)).  To undo
 back to some earlier event use @(':ubt') (see @(see ubt)).  To view the
 current event use @(':pe :here').  To list several @(see events) use @(':pbt')
 (see @(see pbt)).</p>

 <p>Notice the form of the hint in the previous example (see @(see hints)).  It
 specifies a goal to which the hint applies.  @('"Goal"') refers to the
 top-level goal of the theorem.  Subgoals are given unique names as they are
 generated.  It may be useful to suggest that a function symbol be @(see
 disable)d only for Subgoal 1.3.9, say, and a different function @(see enable)d
 only on Subgoal 5.2.8.  Overuse of such @(see hints) often suggests a poor
 global proof strategy.</p>

 <p>We now recommend that you visit @(see documentation) on additional
 examples.  See @(see annotated-acl2-scripts).</p>")

(defxdoc and
  :parents (basics acl2-built-ins)
  :short "Conjunction"
  :long "<p>@('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').</p>

 <p>@('And') is a Common Lisp macro.  See any Common Lisp documentation for
 more information.</p>

 @(def and)
 @(def and-macro)")

(defxdoc annotated-acl2-scripts
  :parents (acl2-tutorial)
  :short "Examples of ACL2 scripts"
  :long "<p>Beginning users may find these annotated scripts useful.  We
 suggest that you read these in the following order:</p>

 <code>
 @(see Tutorial1-Towers-of-Hanoi)
 @(see Tutorial2-Eights-Problem)
 @(see Tutorial3-Phonebook-Example)
 @(see Tutorial4-Defun-Sk-Example)
 @(see Tutorial5-Miscellaneous-Examples)
 </code>

 <p>You can also find useful demos in the @(see community-books) directory,
 @('books/demos/'), and its subdirectories.</p>

 <p>The web page <a
 href='https://www.cs.utexas.edu/users/moore/publications/tutorial/rev3.html'>Brief
 ACL2 Tutorial</a> contains a script that illustrates how it feels to use The
 Method to prove an unusual list reverse function correct.  The screen shots of
 ACL2's proof output are outdated &mdash; in the version shown, ACL2 does not
 print Key Checkpoints, but the concept of key checkpoint is clear in the
 discussion and the behavior of the user.</p>

 <p>See <a
 href='https://www.cs.utexas.edu/users/moore/acl2/contrib/POLISHING-PROOFS-TUTORIAL.html'>Polishing
 Proofs Tutorial</a> for a tutorial on becoming successful at approaching a
 formalization and proof problem in ACL2.  That tutorial, written by Shilpi
 Goel and Sandip Ray, has two parts: it illustrates how to guide the theorem
 prover to a successful proof, and it shows how to clean up the proof in order
 to facilitate maintenance and extension of the resulting book (see @(see
 books)).</p>

 <p>The <a
 href='https://www.cs.utexas.edu/users/moore/publications/tutorial/kaufmann-TPHOLs08/index.html'>ACL2
 Demo Given at TPHOLs 2008</a> by Matt Kaufmann includes scripts and a gzipped
 tar file containing the entire contents of the demos.</p>

 <p>The <a
 href='https://www.cs.utexas.edu/users/moore/publications/tutorial/sort-equivalence'>sort
 equivalence demo</a> is a collection of scripts illustrating both high-level
 strategy and lower-level tactics dealing with the functional equivalence of
 various list sorting algorithms.  Start with the @('README') on that
 directory.  There is also a <a
 href='https://www.cs.utexas.edu/users/moore/publications/tutorial/sort-equivalence.tgz'>gzipped
 tar file</a> with all of these scripts.</p>

 <p>When you feel you have read enough examples, you might want to try the
 following very simple example on your own. (See @(see
 solution-to-simple-example) for a solution, after you work on this example.)
 First define the notion of the ``fringe'' of a tree, where we identify trees
 simply as @(see cons) structures, with @(see atom)s at the leaves.  For
 example:</p>

 @({
    ACL2 !>(fringe '((a . b) c . d))
    (A B C D)
 })

 <p>Next, define the notion of a ``leaf'' of a tree, i.e., a predicate
 @('leaf-p') that is true of an atom if and only if that atom appears at the
 tip of the tree.  Define this notion without referencing the function
 @('fringe').  Finally, prove the following theorem, whose proof may well be
 automatic (i.e., not require any lemmas).</p>

 @({
    (defthm leaf-p-iff-member-fringe
      (iff (leaf-p atm x)
           (member-equal atm (fringe x))))
 })")

(defxdoc append
  :parents (lists acl2-built-ins)
  :short "@(see concatenate) zero or more lists"
  :long "<p>@('Append'), which takes zero or more arguments, expects all the
 arguments except perhaps the last to be true (@('nil')-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 @(tsee 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').</p>

 <p>@('Append') is a Common Lisp function.  See any Common Lisp documentation
 for more information.  See @(see append-without-guard) for a version of
 @('append') that has a guard of @('t').</p>

 @(def append)
 @(def binary-append)")

(defxdoc apply$
  :parents (acl2-built-ins programming)
  :short "Apply a badged function or tame lambda to arguments"
  :long "<p>We recommend that you read the paper <a
  href='https://www.cs.utexas.edu/users/kaufmann/papers/apply/index.html'>``Limited
  Second-Order Functionality in a First-Order Setting''</a> by Matt Kaufmann
  and J Strother Moore for both motivation and foundational details.  You might
  also read @(see introduction-to-apply$)!</p>

  <p>This documentation starts with a <b>glossary</b> of terms.  Then we
  provide some <b>examples</b> and present the <b>specification</b> of
  @('apply$').  Next, we deal with issues related to @('apply$') in
  <b>definitions</b>, <b>stating and proving theorems</b>, <b>guards and guard
  verification</b>, and <b>top-level evaluation</b>.  Finally we exhibit the
  <b>formal definitions</b> @('apply$') and some related concepts.  We have
  sprinkled in a little tutorial material for readability but have not provided
  much motivation for some design decisions.</p>

  <h3>Glossary</h3>

  <p>Here is a brief glossary of terms used in the semantics of @('apply$').
  While we provide links to the documentation of the concepts, we urge you not
  to follow those links until you've understood the big picture!</p>

  <ul>

  <li>@('apply$') &mdash; the ACL2 function that takes two arguments, one
      representing a function and the other listing actuals to be fed to that
      function.  Under certain conditions, @('apply$') applies the function to
      the arguments and returns the result.  @('Apply$') is mutually recursive
      with @(tsee apply$-lambda), @(tsee ev$), and @(tsee ev$-list).
      @('Apply$')'s ``badge'' (see below) is @('(APPLY$-BADGE 2 1 :FN NIL)')
      its arity is 2, its ``out arity'' is 1 (i.e., it returns 1 result), its
      first argument has ``ilk'' @(':FN') and is thus treated as a
      ``function;'' its second argument has ilk @('NIL') and is thus treated as
      an ordinary object.</li>

  <li>@(tsee badge) &mdash; an object associated with some function symbols
      indicating that @('apply$') can ``handle'' them and under what
      conditions.  The badge of a function symbol specifies its arity, its
      ``out arity,'' (i.e., the number of results the function returns), and
      the @(see ilk) of each argument position telling @('apply$') how each
      argument is treated.  The ilks are @(':FN'), @(':EXPR') and @('NIL').
      The association between a non-primitive function symbol and its badge is
      managed by @(tsee warrant)s.  In proofs, @('apply$') must have a warrant
      for every non-primitive function symbol to be applied.  Those warrants
      are provided as hypotheses to the theorem being proved.  Symbols without
      badges cannot be @('apply$')d.  Badges are generated, when possible, by
      @(tsee defwarrant).  (Badges can be generated for @(':')@('program') mode
      functions by @(tsee defbadge), allowing @('apply$') to handle such
      functions in top level evaluation not in proofs.)  Not every function
      symbol can have a badge.</li>

  <li>compiled @('LAMBDA') cache (or simply <i>cache</i> in this context) &mdash; a
      cache in the raw Lisp under ACL2 that supports the application of
      @('apply$') on well-formed, guard verified @('LAMBDA') objects.  Later in
      this Glossary we define ``lambda expression,'' ``@('LAMBDA') object,''
      and ``lambda$ expression'' &mdash; three similar looking phrases with very
      different meanings.  See @(tsee print-cl-cache) for some details of the
      cache.</li>

  <li>evaluation theory &mdash; the logical theory in which expressions
      submitted at the top level of the ACL2 read-eval-print loop are
      evaluated.  The evaluation theory is a consistent extension of the proof
      theory, the latter being the logical theory in which the ACL2 theorem
      prover operates.  The evaluation theory was introduced in ACL2 when
      @(tsee defattach) was added, but it was changed with the introduction of
      @('apply$').  All @(tsee warrant)s introduced by @('defwarrant') are
      assumed true in the evaluation theory but not in the proof theory.  This
      means ACL2 can execute calls of @('apply$') that arise in the evaluation
      of top-level input, but ACL2 cannot evaluate all calls of @('apply$')
      that arise in proofs unless the appropriate warrants are available as
      hypotheses.  See @(see guarantees-of-the-top-level-loop) for some details
      of the evaluation theory and how it differs from the proof theory
      supported by the ACL2 theorem prover.</li>

  <li>lambda expression &mdash; an integral part of ACL2's formal term syntax,
      lambda expressions are the way @('let') expressions and other
      variable-binding idioms are translated into formal terms.  Lambda
      expressions have nothing to do with @('apply$')!  See @(see lambda) for a
      discussion of three confusingly similar but different concepts: lambda
      expressions, @('LAMBDA') objects, and @('lambda$') expressions.  Read
      carefully anytime you see the word ``lambda!''</li>

  <li>@('LAMBDA') object &mdash; an ACL2 list constant, typically of the form
      @('(LAMBDA vars body)') or @('(LAMBDA vars dcl body)') that may be used
      as a ``function'' by @('apply$').  @('Apply$') treats any @(tsee consp)
      object in its first argument position as though it were a @('LAMBDA')
      object.  But it only gives sensible meanings to @(see tame) @('LAMBDA')
      objects.  And only well-formed @('LAMBDA') objects are executed
      efficiently.  But well-formed @('LAMBDA') objects are hard to type by
      hand &mdash; there are many constraints to keep in mind to guarantee
      well-formedness.  See @(tsee well-formed-lambda-objectp) if you really
      want to see all the rules.  But that is generally unnecessary.  We
      <i>strongly</i> recommend not entering @('LAMBDA') objects as quoted
      constants, e.g., @(''(LAMBDA (X) (+ 1 X))') &mdash; which is actually
      ill-formed!  Instead, use @(tsee lambda$), as in @('(lambda$ (x) (+ 1
      x))').  See also @(see lambda) for some clarifications.</li>

  <li>@(tsee lambda$) expression &mdash; an ACL2 macro that allows you to enter
      quoted well-formed @('LAMBDA') objects into your terms by typing
      untranslated expressions that resemble lambda expressions.  The
      @('lambda$') expression @('(lambda$ (x) (+ 1 x))') essentially translates
      into the quoted @('LAMBDA') object @(''(LAMBDA (X) (BINARY-+ '1 X))').
      We say ``essentially'' because @('lambda$') always inserts a
      @('(DECLARE (IGNORABLE v1 ... vn))') listing every formal and tags the
      body with a @(tsee RETURN-LAST) form that indicates it came from a
      translated @('lambda$'). See also @(see lambda) for some
      clarifications.</li>

  <li>@(tsee scion) &mdash; a function that is ancestrally dependent on @('apply$').
      In the early days of @('apply$') we called scions ``mapping functions''
      but in the Lisp community that implies iteration over a list and scions
      are more general.  Of course, a function that iterates over a list
      @('apply$')ing a ``function'' to each element and collecting the results
      is an example of a scion.  But so is function that takes a ``function''
      and applies it in one special situation, e.g., as a test or base case.
      Any function ancestrally dependent on @('apply$') is a scion whether or
      not it takes a ``function'' as an argument or maps over a domain.</li>

  <li>@(see tame) &mdash; the class of functions that @('apply$') knows about; we
      actually talk about ``tame functions,'' ``tame @('LAMBDA') objects,'' and
      ``tame expressions.''  The last are expressions that are evaluable by an
      interpreter named @(tsee ev$) that is mutually-recursive with @('apply$').
      @('Apply$') cannot handle all definable functions: ACL2 is first order
      and if @('apply$') were able to ``handle'' certain functions the logic
      would be inconsistent.</li>

  <li>@(tsee warrant) &mdash; a 0-ary predicate associated with some user-defined
      function symbols that must be a hypothesis of any theorem whose proof
      involves ``expanding'' @('apply$') on such symbols; the warrant gives
      @('apply$') ``permission'' to expand if the arguments to which the
      function is applied are appropriately @(see tame).  The warrant for a
      function specifies the function's @(tsee badge) and how @('apply$')
      behaves on the function symbol.  Warrants (and badges) are computed and
      introduced by the @(tsee defwarrant) event.  Not all function symbols can
      be warranted.</li>

  </ul>

  <p>You will get a much better understanding of these concepts if you read the
  paper cited above.</p>

  <h3>Examples</h3>

  <p>To illustrate @('apply$') and some related concepts we need some
  user-defined functions.  We therefore imagine that the following events
  have been successfully admitted.</p>

  <p><b>We strongly recommend that you include the following book in any
  session in which you intend to use or reason about @('apply$').</b></p>

  @({
  (include-book "projects/apply/top" :dir :system)

  (defun$ sq (x) (* x x))

  (defun$ collect$ (fn lst)
    (if (endp lst)
        nil
        (cons (apply$ fn (list (car lst)))
              (collect$ fn (cdr lst)))))

  (defun$ foldr (lst fn init)
    (if (endp lst)
        init
        (apply$ fn
                (list (car lst)
                      (foldr (cdr lst) fn init)))))

  (defun$ russell (fn x)
    (not (apply$ fn (list x x))))
  })

  <p>Note: @('Collect$') is pre-defined in ACL2 because it is part of the
  support for the @(tsee loop$) statement.</p>

  <p>@('Collect$') and @('foldr') might informally be called ``mapping
  functions'' because they map a given function over some domain and accumulate
  the answers somehow.  They are useful examples of what we call <i>scions
  of</i> @('apply$') or simply <i>scions</i>: functions in which @('apply$') is
  ancestral, i.e., functions that call @('apply$') or call functions that call
  @('apply$'), etc.  @('Russell') is also a scion.  See @(see scion) for
  more.</p>

  <p>Here are some evaluations carried out at the top-level of the ACL2 loop
  after the events above.  Top-level evaluations take place in ACL2's
  evaluation theory (see the discussion of the semantics of @(tsee defattach)),
  which is an extension of the theory in which proofs are conducted.  Put more
  bluntly, the following evaluations won't be carried out in proofs unless you
  have the right hypotheses!</p>

  @({
  ACL2 !>(apply$ 'sq '(5))
  25

  ACL2 !>(collect$ 'sq '(1 2 3 4 5))
  (1 4 9 16 25)

  ACL2 !>(collect$ (lambda$ (x) (* x x)) '(1 2 3 4 5))
  (1 4 9 16 25)

  ACL2 !>(foldr '(1 2 3) 'cons '(4 5 6))
  (1 2 3 4 5 6)

  ACL2 !>(foldr '(1 2 3 4 5)
                (lambda$ (x y)
                  (cons (sq x) y))
                nil)
  (1 4 9 16 25)

  ACL2 !>(foldr '(1 2 3 4)
                (lambda$ (x y) (foldr y 'cons (list x)))
                nil)
  (4 3 2 1)

  ACL2 !>(russell 'natp 3)
  NIL

  ACL2 !>(russell 'consp 3)
  T
  })

  <p>@('Apply$') doesn't always work the way you might want!</p>

  @({
  ACL2 !>(let ((x 'russell))(russell x x))

  ACL2 Error in TOP-LEVEL:  The value of APPLY$-USERFN is not specified when
  the first argument, fn, is RUSSELL, and the second argument, args,
  is (RUSSELL RUSSELL).  Fn has badge (APPLY$-BADGE 2 1 :FN NIL) and
  args is not known to satisfy the tameness requirement of that badge.
  })

  <p> @(tsee Apply$-userfn) is the undefined function called by @('apply$')
  when it is asked to apply a user-defined function symbol instead of a builtin
  function symbol.  The @(tsee warrant) for @('russell') actually specifies the
  value of @('(apply$-userfn 'russell ...)')  under the @(tsee tame)ness
  requirements, and those requirements are violated above.  This is necessary
  to preserve the consistency of the logic.  Otherwise:</p>

  <code>
  (russell 'russell 'russell)
  = {by defun of russell}
  (not (apply$ 'russell (list 'russell 'russell)))
  =  {by the naive expectation that apply$ always ``works''}
  (not (russell 'russell 'russell))
  Contradiction!
  </code>

  <p>Top-level evaluation of @('apply$') expressions raises problems not seen
  anywhere else in ACL2's execution model: While executing syntactically legal
  terms the evaluator can encounter undefined functions or weirdly ill-formed
  terms not caught by the usual ACL2 translation mechanism.  The ACL2
  translation mechanism checks the well-formedness of @(tsee lambda$)
  expressions (and user-typed quoted @('LAMBDA') objects) that occur in
  positions of ilk @(':FN') and are therefore destined for @('apply$').  But
  the translation checks can be defeated.  The @('LAMBDA') object below
  contains a call of the undefined function @('foo') but the error is not
  caught at translation time; it is caught only when the form executed.</p>

  @({
  ACL2 !>(apply$ `(lambda (x) (foo x)) '(5))

  ACL2 Error in TOP-LEVEL:  The value of BADGE-USERFN is not specified
  on FOO because FOO is not a known function symbol.
  })

  <p>Note the <i>backquote</i> on the @('LAMBDA') object.  This defeats the
  check of well-formedness because the @('LAMBDA') object is not @('quote')d.
  We could have equally written</p>

  @({
  ACL2 !>(apply$ (list 'lambda '(x) (cons 'foo '(x))) '(5))
  })

  <p>with the same result.  There is nothing unsound about this.  @('Apply$')
  can take any objects as arguments.  But it won't always ``behave'' as you
  might expect.  One way to explore the edge cases of @('apply$') is to execute
  it on ill-formed input.  In addition, some theorems may require consing up a
  @('LAMBDA') object in terms of objects used elsewhere in the theorem.  See
  example theorem @('[3]') below.</p>

  <p>A peculiar aspect of @('LAMBDA') objects is that they can be written as
  legal ACL2 constants <i>before</i> they are well-formed @('LAMBDA') objects,
  e.g., by referring to undefined functions, @(':program') mode functions,
  unbadged functions, etc.  They are, after all, just arbitrary quoted objects
  and any value in ACL2 can be quoted.  But an ill-formed object can
  <i>become</i> well-formed if the world is appropriately extended, e.g., the
  appropriate @('defun')s, @('defbadge')s, and @('defwarrant')s are made.
  Perhaps worse, they can be well-formed and then <i>become</i> ill-formed by
  an undo.  So at runtime @('apply$') has to check that the function symbol or
  @('LAMBDA') object is appropriate.  There is a sophisticated cache behind the
  execution machinery for @('LAMBDA') objects in the evaluation theory.  See
  @(tsee print-cl-cache).</p>

  <p>Here are some theorems that can be proved about these concepts.  The last
  of the theorems shown below requires two lemmas, named
  @('weird-little-lemma1') and @('weird-little-lemma2'), shown in
  @('books/projects/apply/report.lisp').</p>

  <p>For a summary of how the rewriter handles @('apply$'), @('ev$'), and
  @('loop$') @(see scion)s, see @(see
  rewriting-calls-of-apply$-ev$-and-loop$-scions).</p>

  @({

  ; [1] SQ squares, if you have the warrant for sq!  Imagine for a moment that
  ; we could prove (equal (apply$ 'SQ (list i)) (* i i)) without the warrant
  ; hypothesis shown below.  And imagine that we did so in an encapsulated
  ; environment in which sq was locally defined to be (* x x).  Then imagine we
  ; exported the simpler theorem out of that encapsulate and defined sq to be
  ; (+ 1 (* x x)).  Then ACL2 would be unsound.  Exporting a theorem requires
  ; that the theorem be ancestrally independent of every locally defined
  ; function and the simpler hypothetical theorem is, because the symbol 'SQ is
  ; not ancestrally dependent on sq.  But ACL2 cannot prove the simpler
  ; theorem!  It cannot ``open'' apply$ on 'SQ without the warrant for sq and
  ; the warrant for sq is ancestrally dependent on sq.  So the theorem below
  ; cannot be exported from an environment in which sq is locally defined.
  ; Thus warrants solve the so-called ``LOCAL problem.''

  (thm (implies (warrant sq)
                (equal (apply$ 'SQ (list i))
                       (* i i))))

  ; [2] Collect$ distributes over append for any fn.

  (thm (equal (collect$ fn (append a b))
              (append (collect$ fn a)
                      (collect$ fn b))))

  ; [3] Foldr can be used to collect$, but the collection must
  ; be with an ``ok'' function (a tame function of one
  ; argument).  Note the backquote on the LAMBDA.  This is
  ; a theorem that requires us to cons up a LAMBDA object.

  (thm (implies (ok-fnp fn)
                (equal (foldr lst
                              `(LAMBDA (X Y) (CONS (,fn X) Y))
                              nil)
                       (collect$ fn lst))))
  })

  <h3>Specification of APPLY$</h3>

  <p><b>We strongly recommend that you include the following book in any
  session in which you intend to use or reason about @('apply$').</b></p>

  @({
  (include-book "projects/apply/top" :dir :system)
  })

  @({
  General Form:
  (apply$ fn args)
  })

  <p>where @('fn') is some function symbol or @('LAMBDA') object and @('args')
  is a true list.  Informally, @('apply$') applies the function named by the
  first argument to the appropriate number of elements taken from the second
  argument.  We might express this as:</p>

  <code>
  <b>Naive Specification (for a single-valued function):</b>
  (apply$ 'fn args) = (fn (nth 0 args) ... (nth (- n 1) args))

  <b>Naive Specification (for a multi-valued function):</b>
  (apply$ 'fn args) = (mv-list k (fn (nth 0 args) ... (nth (- n 1) args)))
  </code>

  <p>where @('fn') is of arity @('n') and @('k') is the ``out arity'' of
  @('fn') (the number of returned values).  <b>However</b>, these naive
  specifications are guaranteed only if either (i) @('fn') is a function symbol
  that has a @(tsee badge) and @('args') satisfies the @(see tame)ness
  requirements of the badge, or (ii) @('fn') is a well-formed @('LAMBDA')
  object that returns 1 result.  The tameness requirement is that if an element
  of @('args') is in an argument position of @('fn') with ilk @(':FN') then the
  element must satisfy @('tamep-functionp') and if the element is in an
  argument position of ilk @(':EXPR') it must satisfy @('tamep').  See @(tsee
  badge) for further discussion of condition (i).  As for (ii), rather than
  explain ``well-formed @('LAMBDA') object'' here we encourage you to write
  @(tsee lambda$) expressions when you want to @('apply$') a @('LAMBDA')
  object.</p>

  <p>The @(see ilk)s of @('apply$') are @(':FN') and @('NIL') respectively,
  telling us that @('apply$') treats its first argument as a ``function'' and
  its second as an ordinary object (never as a function).  Initially
  @('apply$') and several functions used in the translation of @('loop$')
  statements are the only symbols in ACL2 with an ilk of @(':FN').  However as
  @(tsee defwarrant) is used successfully on @(see scion)s &mdash; functions that
  somehow call @('apply$') &mdash; user-defined symbols can have ilk @(':FN')
  too.</p>

  <p>@('Apply$') has a guard, namely @('(apply$-guard fn args)').  This is an
  exceptionally weak guard, requiring only that @('args') be a true-list and,
  if @('fn') is a cons &mdash; which is automatically treated as a @('LAMBDA')
  object &mdash; the length of @('args') be the length of the second element of
  @('fn').  We discuss <b>guards and guard verification</b> in a subsequent
  section.</p>

  <p><b>Note for Experts</b>: Technically, @('apply$') treats any @('consp')
  object as a @('LAMBDA') object.  But the results are as you'd naively expect
  only if the object is a @(see tame) @('LAMBDA') object.  However, we
  frequently write as though the object must be <i>well-formed</i>, which is
  different from but implies tameness.  What's going on?  The reason for this
  and related discrepancies in the documentation is that there is a tension
  between the logical definition of @('apply$') and the practical business of
  executing it.  The former involves the existence of a model, soundness, and
  the difficulty of proving theorems about @('apply$').  The latter involves
  the Common Lisp compiler.  We want the logical foundations to be simple to
  make it easier to reason about @('apply$'), but the compiler imposes
  unavoidable and complicated restrictions.  The upshot is that the logical
  foundations assign meaning to @('LAMBDA') objects that cannot be compiled.
  Applying merely ``tame'' @('LAMBDA')s is slower than applying ``well-formed''
  ones.  In a sense, by acting like ``tame @('LAMBDA') objects'' and
  ``well-formed @('LAMBDA') objects'' are synonymous we're trying to trick you!
  If you ever have occasion to formally express the restrictions on @('apply$')
  in some theorem, use @('tamep-functionp').  But when you write concrete
  @('LAMBDA') constants, try to keep them well-formed.  We encourage this by
  providing @(tsee lambda$) and by enforcing full blown well-formedness checks
  &mdash; not just tameness checks &mdash; in translate on every quoted @('LAMBDA')
  object entered in a @(':FN') slot.  And we give you ways to circumvent these
  checks &mdash; see @(see gratuitous-lambda-object-restrictions) &mdash; if you really
  mean to supply ill-formed @('LAMBDA') objects to @(':FN') slots.</p>

  <p>Badges are assigned by @(tsee defwarrant), and also by @(tsee defbadge).
  See @(tsee badge) for documentation about how to find out whether a function
  has a badge and how to interpret a badge.  The terms ``out arity'' and
  ``tameness requirements,'' used above, are explained there too.</p>

  <p>Intuitively, the badge of @('fn') tells @('apply$') how each formal of
  @('fn') is used in the definition of @('fn') and there are only three
  ``ilks'' of use.  Ilk @(':FN') means the formal is used exclusively as a
  function, meaning the formal can be passed into @(':FN') slots of other
  functions and eventually reaches @('apply$'), but it is never touched by
  other ACL2 functions.  Ilk @(':EXPR') means the formal is used exclusively as
  an expression, meaning the formal may be passed into @(':EXPR') slots of
  other functions and eventually reaches @(tsee ev$), but is never otherwise
  touched.  Finally, ilk @('NIL') means the formal is treated as an ordinary
  ACL2 object and, in particular, never used as either a function or an
  expression.  The ``tameness requirement'' on each actual is determined by the
  ilk of the corresponding formal: actuals in @(':FN') slots must satisfy
  @('tamep-functionp'), actuals in @(':EXPR') slots must satisfy @('tamep'),
  and there are no requirements on actuals in ilk @('NIL') slots.  For
  discussions of @('tamep-functionp') and @('tamep') see the topic @(see
  tame).</p>

  <p>Generally speaking, if you want to be able to @('apply$') a function you
  should introduce it with @(tsee defun) and then call @(tsee defwarrant) on
  the function name, or use @(tsee defun$), which is a convenient abbreviation
  for the above sequence of events.  But @('defun$') only works for @(':logic')
  mode functions because @('defwarrant') enforces that restriction.  If you
  want to @('apply$') a @(':program') mode function you should define it with
  @('defun') and then call @('defbadge') on its name.</p>

  <p>We summarize the specification of @('apply$') with an example.
  Consider</p>

  @({  (apply$ 'foldr
          '((1 2 3)     ; actual 1
            cons        ; actual 2
            (4 5 6)))   ; actual 3
  })

  <p>The badge of @('foldr'), computed by @('(badge 'foldr)'), is
  @('(APPLY$-BADGE 3 1 NIL :FN NIL)').  The arity is @('3'), the out arity is
  1 (@('foldr') is single-valued) and the ilks list is @('(NIL :FN NIL)').
  Thus the first and third formals have ilk @('NIL') and are treated as
  ordinary objects; the second formal has ilk @(':FN') and is treated as a
  function.  Thus, the tameness requirement is that the second actual to a call
  of @('foldr') must satisfy @('tamep-functionp').  Referring to the
  specification above, we see that the @('apply$') term has the ``naive
  specification'' since @('foldr') has a badge, its out arity is 1, and its
  second actual, @('cons'), satisfies @('tamep-functionp'). That is,</p>

  @({  (apply$ 'foldr
          '((1 2 3)     ; actual 1
            cons        ; actual 2
            (4 5 6)))   ; actual 3
  =
  (foldr '(1 2 3) 'cons '(4 5 6))
  =
  '(1 2 3 4 5 6)})

  <p>The first equation above is just the naive specification of @('apply$')
  and the second equation is just the definition of @('foldr').</p>

  <p>Formals are classified by @(tsee defwarrant) when it tries to compute the
  badge of a function.  What are the rules that lead to a formal being assigned
  ilk @(':FN'), for example?  What does ilk @(':FN') actually signify?</p>

  <p>Let <i>v</i> be the <i>i </i>th formal parameter of a badged function
  <i>fn</i>.  If the badge says that <i>v</i> has ilk @(':FN') then we know
  that <i>v </i> is ``used as a function'' in the definition of <i>fn </i>,
  i.e., the value of <i>v </i> eventually makes its way into the first argument
  of @('apply$').  Furthermore, <i>v </i> is never used any other way: every
  place <i>v </i> occurs in the body it is treated as a function.  And finally,
  in every recursive call of <i>fn </i> <i>v </i> is passed identically in the <i>i
  </i>th argument position of every recursive call.</p>

  <p>If the badge says that formal variable <i>v </i> has ilk @(':EXPR') then
  it signifies analogous conditions except that instead of eventually getting
  into the first argument of @('apply$') it eventually gets into the first
  argument of @('ev$').  We say such formals are ``used as expressions.''
  @(tsee Ev$) is the natural notion of evaluation in this context: look up the
  values of variables in the alist argument to @('ev$'), return quoted
  constants, and otherwise @('apply$') function symbols and @('lambda') objects
  to the recursively obtained list of values returned by evaluating the
  actuals.  However, @('ev$') first checks that the expression is @(tsee
  tamep).</p>

  <p>If the badge says a formal <i>v </i> has ilk @('NIL') in the definition of
  <i>fn </i> then <i>v </i> is <i>never used </i> as a function or as an
  expression in the definition.</p>

  <p>It is the job of @(tsee defwarrant) to analyze a definition and assign
  ilks, if possible.  But it may not be possible!  For example,</p>

  @({(defun foo (x) (apply$ x (list x)))})

  <p>is such a definition.  The formal @('x') is used as a function in its first
  occurrence but is not used as a function in its second.  Thus</p>

  @({(defwarrant foo)})

  <p>will fail.</p>

  <p>When successful, @(tsee defwarrant) also defines the @(tsee warrant)
  function for the function it analyzed.  Warrants are crucial to stating and
  proving theorems about function symbols being applied with @('apply$').  We
  illustrated warrants in the ``Examples'' section above and discuss them
  further in the section on ``Theorems Involving @('Apply$')'' below.  See also
  @(tsee warrant).</p>

  <p>@('Apply$') is a defined function in the ACL2 source code.  We exhibit its
  definition at the end of this documentation but you may also see its
  definition by doing</p>

  @({
  ACL2 !>:pe apply$
  })

  <p>The definition is mutually recursive with</p>

  <ul>
  <li>@(tsee apply$-lambda): used by @('apply$') to handle the case when
  the first argument to @('apply$') is a @('LAMBDA') object.</li>

  <li>@(tsee ev$): used by @('apply$-lambda') to evaluate the body of a
  @('LAMBDA') object in an environment binding the object's formal variables to
  the actuals.</li>

  <li>@(tsee ev$-list): used by @('ev$') to evaluate a list of expressions in
  an environment binding formals to actuals.</li>

  </ul>

  <p>@('Apply$') calls three undefined functions:</p>

  <ul>

  <li>@(tsee apply$-userfn): used by @('apply$') when it is asked to apply
  anything other than a @('LAMBDA') object or a built-in function symbol.  In
  the evaluation theory, we attach a function to @('apply$-userfn') that
  explicitly enforces the tameness requirements for each user-defined
  @(':logic') mode function symbol that has had a badge computed by @(tsee
  defwarrant) and, if those requirements are met, applies the corresponding
  function.  Magically, that attachment to @('apply$-userfn') can also evaluate
  @(':program') mode functions with badges created by @(tsee defbadge).  We say
  ``magically'' because there are no axioms that explain this behavior, just as
  there are no axioms that explain how you can evaluate ordinary calls of
  @(':program') mode functions in the evaluation theory.  But in the proof
  theory @('apply$-userfn') remains undefined.  The value of @('(apply$-userfn
  'fn ...)'), and thus of @('(apply$ 'fn ...)'), is specified by a special
  hypothesis, called the ``warrant for @('fn').''  You can't prove anything
  interesting about the behavior of @('apply$') on a user-defined function
  symbol @('fn') unless the warrant for @('fn') is a governing hypothesis.  We
  discuss warrants in @(tsee warrant).  See also @(tsee defwarrant).</li>

  <li>@('untame-apply$'): used by @('apply$') when it is asked to deal with a
  situation in which tameness is violated.</li>

  <li>@('untame-ev$'): used by @('ev$') when it is asked to deal with a
  situation in which tameness is violated.</li>

  </ul>

  <h3>Definitions Involving on @('Apply$')</h3>

  <p>In one sense, @('apply$') is just an ordinary ACL2 function that takes two
  arguments and returns one result.  Like all ACL2 functions, @('apply$') is
  untyped.  You can supply any two objects as arguments and the axioms tell you
  what the result is &mdash; though sometimes the result is delivered by an
  undefined function.</p>

  <p>But in a deeper sense, if you want @('apply$') to ``behave,'' and in
  particular if you want functions that use @('apply$') to ``behave,'' you have
  to follow certain rules.  For example, ACL2 must be able to determine whether
  a formal parameter is ``used as a function'' in a given definition.
  Basically, you will want every @(':logic') mode function that you define to
  be processed by @('defwarrant') so that it gets a badge and warrant if at all
  possible and at least has a chance of being applied as expected by
  @('apply$').</p>

  <p>The macro @('defun$') is just an abbreviation for a @('defun') followed by
  a @('defwarrant') and it is easy to imagine the other ACL2 definitional
  idioms introduced in the ACL2 Community Books eventually being extended to
  include a subsequent @('defwarrant').</p>

  <p>So the question becomes ``What rules must a @('defun') obey in order to be
  processed successfully by @('defwarrant')?''  The full answer is given in the
  documentation for @(tsee defwarrant).  But here are some guidelines to
  follow:</p>

  <ul>
  <li>use @(':logic') mode,</li>
  <li>use a measure that either returns a natural number or a
      lexicographic combination of natural numbers as defined by the @('llist')
      function in the Community Books at @('books/ordinals/'),</li>
  <li>make sure every function used in the definition has a badge,</li>
  <li>ensure that every @(':FN') slot in the body is occupied either by
      a formal parameter or a quoted, badged function symbol or @(tsee lambda$)
      expression, and</li>
  <li>ensure that no parameter occupying a @(':FN') slot is ever used in a
      slot of any other ilk, and</li>
  <li>ensure that every parameter passed into a @(':FN') slot is passed into
      the same argument position in any recursive calls of the function being
      defined.</li>
  </ul>

  <p>You can certainly violate some of these rules and still get an admissible
  definition.  For example @('(defun rus (x) (not (apply$ x (list x))))') is
  admissible and you can run it on some arguments, e.g., @('(rus 'consp)')
  evaluates to @('T').  You can even prove @('(equal (rus 'consp) t)').  But
  @('(defwarrant rus)') fails because @('rus') violates the rules.  So you will
  not be able to @('apply$') @(''rus').</p>

  <p><b>Note for Experts</b>: One may wonder why it is possible to warrant a
  function, @('fn'), that calls badged but unwarranted functions.  Naively one
  might expect the semantics of @('(apply$ 'fn args') would involve the
  @('ev$') of the body of @('fn') and therefore require the successful
  application (via @('apply$')) of subfunctions in the body.  But that
  expectation is incorrect.  The semantics of @('(apply$ 'fn args)') as
  formalized by the warrant for @('fn') says that (under restrictions on the
  tameness of the arguments) @('(apply$ 'fn args)') is @('(fn (car args) (cadr
  args) ...)').</p>

  <h3>Theorems Involving @('Apply$')</h3>

  <p>Because @('apply$') is undefined on user-defined function symbols and
  warrant hypotheses specify the tameness requirements and value of @('apply$')
  on such symbols, you can't prove much about the application of particular
  user-defined symbols unless you provide the corresponding warrants as
  hypotheses.</p>

  <p>To emphasize this point, suppose @('sq') has been introduced with
  @('defun$') as shown above, then the following top-level evaluation is
  possible:</p>

  @({
  ACL2 !>(apply$ 'sq '(5))
  25
  })

  <p>You might expect to be able to prove the obvious little theorem</p>

  @({(thm (equal (apply$ 'sq '(5)) 25))})

  <p>However, you would be wrong!  While ACL2's evaluation theory assumes all
  warrants, the proof theory does not.  (If it did we could suffer the
  @('LOCAL') problem mentioned in example theorem @('[1]') above and in @(see
  introduction-to-apply$).)  Logically, there is no connection between the
  symbol @(''SQ') and the user-defined function @('sq').  That connection is
  established by warrant.  All the necessary warrants must be explicitly
  provided as hypotheses by the user.</p>

  <p>The warranted version of the little theorem above is easily proved.</p>

  @({(thm (implies (warrant sq) (equal (apply$ 'sq '(5)) 25)))})

  <p>Here @('(warrant sq)') is just an abbreviation for a call of the 0-ary
  function symbol @('apply$-warrant-sq') which is the name of the warrant for
  @('sq').  @('Apply$-warrant-sq') is introduced when @('(defwarrant sq)')
  completes successfully.  In particular, the following is a theorem:</p>

  @({
      (warrant sq)
    <-->
      (force (apply$-warrant-sq))
    <-->
      (((badge 'SQ) = '(APPLY$-BADGE 1 1 . T))
       &
       ((apply$ 'SQ args) = (sq (car args))))
   })

  <p>Note that the @(tsee warrant) macro @(tsee force)s the warrants for the
  functions listed.  But logically @('force') is just the identity.</p>

  <p>Thus, the warrant for @('sq') specifies the value of @('(badge 'sq)') and
  of @('(apply$ 'sq ...)').  Operationally, by forcing the warrant it means the
  absence of a warrant among the hypotheses of a conjecture which is otherwise
  provable just results in a forcing round that highlights the need for the
  warrant.</p>

  <p>If you try to prove the unwarranted version of the little theorem about
  @(''sq') it fails in a forcing round with</p>

  @({
  [1]Goal
  (APPLY$-WARRANT-SQ)
  })

  <p>This is a clear indication that you forgot to provide the warrant.</p>

  <p>You might worry that theorems burdened by warrants are vacuously valid
  because it might be impossible to satisfy all the warrant hypotheses.  You
  needn't worry about this.  <i>There is a model of @('apply$') and all of its
  scions that makes every warrant issued by @('defwarrant') valid.</i> The
  proof of this is sketched in <a
  href='https://www.cs.utexas.edu/users/kaufmann/papers/apply/index.html'>``Limited
  Second-Order Functionality in a First-Order Setting''</a> by Matt Kaufmann
  and J Strother Moore and fully fleshed out in the comment titled <tt>Essay on
  Admitting a Model for Apply$ and the Functions that Use It</tt> in the ACL2
  source file @('apply-raw.lisp').</p>

  <p>So there are four lessons here:</p>

  <p><b>Lesson 1:</b> When stating theorems involving @('apply$') or scions on
  concrete user-defined functions, provide as additional hypotheses the
  warrants for all user-defined functions that @('apply$') will encounter
  during the proof.  This generally means you should add the hypothesis
  <tt>(warrant </tt><i>fn1 fn2 ... fnk</i><tt>)</tt> typically listing every
  function symbol that appears inside a quoted constant destined for
  @('apply$') or @('ev$') in your conjecture.  In particular, you should
  include every quoted function symbol appearing in a @(':FN') slot of
  @('apply$') or any scion, including every function symbol appearing in the
  body of any @('LAMBDA') object or @('lambda$') term or any @('until'),
  @('when'), or body expressions of @('loop$')s.  (Macro expansion in
  @('lambda$')s and @('loop$')s may introduce function symbols not evident in
  the untranslated forms.  See @(':')@(tsee translam) and @(':')@(tsee
  trans).)</p>

  <p><b>Lesson 2:</b> You need not worry that adding warrant hypotheses makes
  your theorems vacuously valid!  There is a model of @('apply$') and all your
  scions in which all warrants are valid.</p>

  <p><b>Lesson 3:</b> If a proof involving @('apply$') or a scion fails in a
  forcing round with a checkpoint whose conclusion is the warrant for some
  function, you should remember Lesson 1 and include the warrant for that
  function symbol in the hypotheses of your conjecture!  That is, if you forget
  to supply a warrant but your conjecture is otherwise provable, ACL2's
  checkpoints will often remind you.  (It is possible, in the absence of an
  explicit warrant hypothesis, for a proof to fail before the prover detects
  that only the warrant is missing.)</p>

  <p><b>Lesson 4:</b> If a proof involving @('apply$') or a scion fails here
  are some things to think about.  The basic question is whether something is
  ``wrong'' with one or more function symbols supposedly handled by
  @('apply$').  You have to identify which quoted function symbols are not
  being simplified or expanded.  Typically you'll see a checkpoint with a term
  like @('(apply$ 'fn ...)') or @('(ev$ '(fn ...)  ...)') that you expect would
  be expanded into an actual call of @('fn').  In that case, @('fn') is of
  interest.  You should realize that problems of these sorts can drastically
  slow down a proof attempt.  We have seen example proofs where failure to
  simplify an @('apply$') term slowed the proof-attempt down by several orders
  of magnitude.  Here are some questions you should ask yourself about
  @('fn').</p>

  <ul>

  <li>Is @('fn') defined and in @(':logic') mode?  If @('fn') is in
  @(':program') mode it is treated by the prover as an undefined symbol.  You
  should try to convert it @(':logic') mode with @(tsee
  verify-termination).</li>

  <li>Is @('fn') warranted?  If not, see @(tsee defwarrant).  If @('fn') is
  warranted then it is possible @('fn') is not the problem.  Maybe the warrant
  for @('fn') was not provided as a hypothesis?  Normally, missing warrant
  hypotheses are forced, but the proof might have failed for other reasons
  before the warrant for @('fn') was forced.  But you should ask whether
  forcing is disabled; see @(tsee force).</li>

  <li>If you see @('(apply$ 'fn ...)') then perhaps the rewrite rule
  @('APPLY$-fn') is disabled.  That rule is the one that forces the warrant for
  @('fn') and it was proved when @('fn') was warranted.</li>

  <li>Consider how the rewriter handles @('apply$') terms, by reading
  @(see rewriting-calls-of-apply$-ev$-and-loop$-scions) and inspecting
  the enabled/disabled status of the runes mentioned there.</li>

  </ul>

  <p>These issues are discussed further in the documentation for @(tsee
  warrant).</p>

  <p>An unfortunate implication of the need for warrants is highlighted during
  the proofs of measure conjectures while admitting new definitions.
  Consider</p>

  @({
  (defun$ my-cdr (x) (cdr x))

  (defun$ my-len (x)
    (if (endp x)
        0
        (+ 1 (my-len (apply$ 'my-cdr (list x))))))
  })

  <p>The definition of @('my-len') fails!  The reason is that without the
  warrant for @('my-cdr') we cannot prove that the measure decreases in the
  recursion above.  Unfortunately, there is no way to provide a warrant in a
  definition.  At the moment we advise users to avoid the use of @('apply$') &mdash;
  and functions that use @('apply$') &mdash; in ``termination-critical'' roles.  By
  that we mean do not use @('apply$') if its properties are important to proofs
  of your measure conjectures.  This is easy advice to implement in the case of
  @('my-len'), i.e., replace the recursive call above by @('(my-len (my-cdr
  x))').  However, in more sophisticated definitions, e.g., where a @(tsee
  loop$) is being used in recursive calls and the @('loop$') calls user-defined
  functions in its body, following this advice means replacing that @('loop$')s
  by a recursive function.  That is unfortunate since the whole point of
  @('loop$') is to avoid the introduction of such functions!  We hope to
  address this limitation in the future, e.g., by making the definition of
  @('my-len') above be conditional on the warrant for @('my-cdr').</p>

  <h3>Guards and Guard Verification</h3>

  <p>As noted, @('apply$') has a guard of @('(apply$-guard fn args)') and is
  itself guard verified.  The guard is weak, basically requiring that @('fn')
  either be a symbol or a @('LAMBDA') object, that @('args') be a true-list,
  and, when @('fn') is a @('LAMBDA') object, the length of the list of formals
  is equal to the length of @('args').  To verify the guards of a scion you
  must make sure these properties hold of every application of anything in a
  @(':FN') slot.  Mainly you must make sure that every time a function object
  is @('apply$')d, it is applied to a list of the right length.</p>

  <p>Note also that @(see mixed-mode-functions), i.e., @(':logic') mode
  functions that use @(':program') mode functions in slots of @(see ilk)
  @(':FN') or @(':EXPR'), cannot be guard verified.</p>

  <p>But guards arise in another way in connection with @('apply$').  How does
  @('(apply$ fn args)') behave when @('fn') has guards?  The short answer is:
  logically speaking, @('apply$') completely ignores guards.  Guards in ACL2 are
  ``extra-logical.''</p>

  <p>Let's define and warrant a well-guarded version of ``square'',</p>

  @({
  (defun$ squ (n) (declare (xargs :guard (natp n))) (* n n))
  })

  <p>@('Squ') is guard verified.  Now let's consider the little conjecture:</p>

  @({
  (thm (implies (warrant squ) (equal (apply$ 'SQU (list x)) (* x x))))
  })

  <p>Do we need need to require @('(natp x)')?  We would if the logical
  definition of @('apply$') checked the guard of @('fn') before interpreting
  it.  But it does not check.  It just behaves as specified above.  So,
  regardless of whether the guard is satisfied or not, @('(apply$ 'squ (list
  x))') naively expands (under the warrant) to @('(squ x)'), from which the
  rest of the proof follows.</p>

  <p>However, now let's do a top-level evaluation of this @('apply$') term:</p>

  @({
  ACL2 !>(apply$ 'SQU (list 'NAN))

  ACL2 Error in TOP-LEVEL:  The guard for the function call
  (SQU N), which is (NATP N), is violated by the arguments
  in the call (SQU 'NAN).
  })

  <p>(Remember that ACL2's evaluation theory effectively assumes all warrants.)
  What happened?  @('Apply$') expanded to @('(SQU 'NAN)') and that caused the
  usual guard violation, given the default configuration of @(tsee
  set-guard-checking).</p>

  <p>A similar guard violation error is signaled if a guarded @('LAMBDA')
  object is @('apply$')ed to something violating its guard.</p>

  <p>But now consider</p>

  @({
  (defun$ strange (x)
    (declare (xargs :guard t))
    (apply$ 'SQU (list x)))
  })

  <p>This succeeds and @('strange') is now a guard verified, warranted
  function, with a guard of @('T').  This might be surprising since (a) the
  guard of @('strange') tells us nothing about @('x'), (b) @('SQU') is applied
  to @('x'), and (c) we know the guard of @('SQU') requires its argument to be
  a @('natp').  Guard verification ignores the guards of a quoted function
  symbol being applied by a scion.  This may be particularly offensive to one's
  intuitions when the scion is @('apply$') itself, since the appropriate
  information is available.  But consider a call of an arbitrary user-defined
  scion, e.g., @('(my-scion 'SQU x)').  To what arguments will @('my-scion')
  @('apply$') @('SQU')?  And how can the definition of @('my-scion') even
  specify what functional objects are acceptable in its first argument?  This
  is a limitation suffered by ACL2 that a logic with a suitably expressive type
  system would not suffer.  Our way of coping with it is to ignore the guard
  here and make sure that when @('apply$') applies the function symbol executes
  it checks the guard of the symbol.</p>

  <p>Guard verification does not ignore guards of a quoted lambda object being
  @('apply$')ed.  Thus, for example, while @('strange') can be guard
  verified,</p>

  @({
  (defun$ stranger (x)
    (declare (xargs :guard t))
    (apply$ (lambda$ (e) (SQU e)) (list x)))
  })

  <p>cannot be guard verified, because guard verification tries to verify the
  guards of every @('lambda') object in a @(':FN') slot so that the @('lambda')
  object can be marked as guard verified in the compiled @('lambda') cache
  (see @(tsee print-cl-cache)).  But guards of @('lambda') objects must be
  verified independently of the context in which they are used.  To be specific,
  even</p>

  @({
  (defun$ stranger (x)
    (declare (xargs :guard (natp x)))
    (apply$ (lambda$ (e) (SQU e)) (list x)))
  })

  <p>cannot be guard verified because the @('lambda') object's guards are
  verified independently of the context.  The @('lambda') object must carry
  its own guard, as in</p>

  @({
  (defun$ stranger (x)
    (declare (xargs :guard (natp x)))
    (apply$ (lambda$ (e)
              (declare (xargs :guard (natp e)))
              (SQU e))
            (list x)))
  })

  <p>The last definition of stranger can be guard verified, the @('lambda')
  object is so marked in the cache and compiled, and if that @('lambda') object
  is used in any other context it is recognized as being guard verified.  The
  guard for that @('lambda') is checked when the object is @('apply$')ed but if
  the check approves then the body of the @('lambda') is executed as compiled
  code without further guard checking.</p>

  <p>While @('apply$') is not evident in a @(tsee loop$) statement like</p>

  @({
  (loop$ for e in lst collect (SQU e))
  })

  <p>similar treatment is given.  In particular, the @('loop$') above cannot
  be guard verified but</p>

  @({
  (loop$ for e in lst collect :guard (natp e) (SQU e))
  })

  <p>can be and is compiled into a Common Lisp @('loop').  Recall also from
  the @(tsee loop$) documentation that the formal semantics of the above
  statement is essentially</p>

  @({
  (collect$ (lambda$ (e)
              (declare (xargs :guard (natp e)))
              (SQU e))
            lst)
  })

  <p>so guard verification of the @('loop$') also compiles and marks that
  @('lambda') expression as guard verified.</p>

  <p>So now let's return to consideration of</p>

  @({
  (defun$ strange (x)
    (declare (xargs :guard t))
    (apply$ 'SQU (list x)))
  })

  <p>which we've seen is guard verified despite the fact that @('SQU') expects
  a natural number and will not necessarily be given one.  What happens when we
  call @('strange') on a non-natural?</p>

  @({
  ACL2 !>(strange 'NAN)

  ACL2 Error in TOP-LEVEL:  The guard for the function call (SQU N),
  which is (NATP N), is violated by the arguments in the call (SQU 'NAN).

  ACL2 !>:q

  Exiting the ACL2 read-eval-print loop.  To re-enter, execute (LP).
  ? (strange 'nan)

  ACL2 Error in ACL2-INTERFACE:  The guard for the function call (SQU N),
  which is (NATP N), is violated by the arguments in the call (SQU 'NAN).
  })

  <p>We see that we can provoke a guard violation with @('strange')
  even though it is guard verified with a guard of @('T').  Furthermore,
  we get the error both in the ACL2 read-eval-print loop and in the raw
  Lisp under ACL2.  (Be careful though about exiting the ACL2 loop; see @(see
  q).)</p>

  <p>This might at first violate your understanding of the link between ACL2
  and Common Lisp.  Naively, a guard verified ACL2 function with a guard of
  @('T') never causes a runtime error in Common Lisp.  But that's not quite
  what the guarantee is.  Such a function will never cause a hard Lisp error,
  other than possibly resource errors like running out of memory or stack
  space.  Neither of the errors above were signaled by Common Lisp.  They were
  ``soft'' ACL2 errors.  In particular, when @('apply$') calls @('squ') above,
  even when running in raw Lisp, it actually calls the executable counterpart
  of @('squ'), which checks guards at runtime and executes properly under the
  ACL2 axioms.</p>

  @({
  ACL2 !>(set-guard-checking :none)

  Turning off guard checking entirely.

  ACL2 >(strange 'nan)
  0
  })

  <p>The last evaluation can be explained by the fact that ACL2 multiplication
  defaults non-numbers to 0.</p>

  <p>We discuss the evaluation of ground @('apply$') terms in the evaluation
  theory further below.</p>

  <p>When the guard conjectures of a function are proved all necessary warrants
  are assumed.  This is unlike what happens when the measure conjectures are
  proved.  The reason we can assume warrants during guard verification is that
  guard verification is relevant in the evaluation theory, where attachments
  are allowed and all warrants have true attachments.</p>

  <h3>Top-Level Evaluation of Apply$</h3>

  <p>As noted, ACL2's evaluation theory implicitly assumes all warrants
  produced by @(tsee defwarrant).  See @(see
  guarantees-of-the-top-level-loop). Since top-level evaluation in ACL2 is
  conducted in the evaluation theory, ground calls of @('apply$') &mdash;
  whether literally in top-level input to the ACL2 read-eval-print loop or
  hidden inside scions called from the top-level &mdash; can be evaluated on
  quoted warranted function symbols and @(tsee lambda$) expressions &mdash;
  provided the @(see tame)ness restrictions are met.  This is in contrast to
  opportunities for evaluation of ground @('apply$') expressions arising in
  proofs, where warrant hypotheses must be explicit.</p>

  <p>In this section we focus on calls of @('apply$') arising in the evaluation
  theory.  We start with a discussion of the use of @('apply$') with warranted
  @(':logic') mode functions.  We then describe how @('apply$') handles badged
  @(':program') mode functions.  Note that a mere badge is <i>not</i>
  sufficient for evaluation when using @('apply$') on a @(':logic') mode
  function that is not warranted; see @(tsee defbadge) and @(see
  guarantees-of-the-top-level-loop) for discussion of this case.  In short:
  evaluation involving @(':logic') mode functions is expected to respect the
  evaluation theory, and while @('defwarrant') extends the evaluation theory
  appropriately, @('defbadge') does not.</p>

  <p>Evaluation of @('apply$') terms in the evaluation theory respects guards
  on quoted function symbols and @(tsee lambda$) expressions (which is to say,
  on the quoted well-formed @('LAMBDA') objects that @(tsee lambda$) produces).
  So consider a call of @('apply$') on @('fn') and @('args') in the evaluation
  theory, where @('fn') is a warranted function symbol or a well-formed (and
  thus tame) @('LAMBDA') object.  Here's what happens.  Except where noted, the
  description below applies both to warranted @(':logic') and badged
  @(':program') mode functions.</p>

  <p>@('Apply$') determines whether @('fn')'s tameness restrictions are met by
  @('args').  Tameness is a syntactic property and so can be checked.  If the
  function's tameness restrictions are not met, an error is caused.</p>

  <p>If the tameness restrictions are met, @('apply$') determines whether
  @('fn') has been guard verified.  In the case of function symbols this is a
  simple lookup on the property list of @('fn').  (Of course, this check fails
  for @(':program') mode functions.)  In the case of @('LAMBDA') objects it is
  a cache query (see @(tsee print-cl-cache)) and if the query reveals that we
  have not yet tried to verify the guards of this @('LAMBDA') object,
  @('apply$') uses tau reasoning alone (see @(see
  introduction-to-the-tau-system)) to try to verify the guard conjectures.</p>

  <p><b>Note:</b>An important distinction between the runtime handling of
  function symbols versus @('LAMBDA') objects by @('apply$') is that function
  symbols can only be guard verified by prior events, e.g., the introductory
  @(tsee defun) or a subsequent @('verify-guards'), but @('apply$') tries to
  verify the guards of @('LAMBDA') objects <i>on the fly</i>!  The reason for
  this distinction is that we anticipate that many @('LAMBDA') objects will not
  be associated with any event.  For example, an ACL2 macro might generate a
  call of a scion on a never-before-seen @('LAMBDA') object and that
  @('LAMBDA') object may only be seen by the top-level evaluator.  We discuss
  this further in @(tsee verify-guards)</p>

  <p>If @('fn') is guard verified, @('apply$') next checks whether @('fn')'s
  guard holds of the actuals in @('args').  This is done by evaluation of the
  compiled code for the guard on @('args').</p>

  <p>If the guard check of @('args') succeeds, a compiled version of @('fn') is
  applied to @('args').  If the check fails, a guard violation is signaled or
  else the application of @('fn') to @('args') is interpreted under the
  definitional axioms of @('apply$') and @('ev$'), depending on how @(tsee
  set-guard-checking) has been configured.</p>

  <p>Finally, if @('fn') is not guard verified, the application of @('fn') to @('args')
  is interpreted under the definitional axioms of @('apply$') and @('ev$').</p>

  <p>We discuss the cache that supports @('LAMBDA') application in @(tsee
  print-cl-cache).  See also the discussion of guard verification in @(tsee
  lambda$).  It should be noted that a @('LAMBDA') object can also be guard
  verified using the @(tsee verify-guards) event.  This brings the full power
  of the prover to bear on the guard verification of the @('LAMBDA') object,
  instead of relying just on the tau system.</p>

  <p>Users are accustomed to executing @(':program') mode functions at the
  top-level of the ACL2 read-eval-print loop.  Indeed, the prover itself and
  the various event commands are mostly written in @(':program') mode.
  Furthermore, the evaluation theory is described as an extension of the proof
  theory, i.e., as an axiomatic theory.  And yet no part of that axiomatization
  explains how @(':program') mode functions are run!  It simply isn't
  important.  The implementation supports it and no questions are asked.  We,
  the implementors of ACL2, view top-level evaluation of @(':program') mode
  functions as a convenience not affecting the consistency of the proof theory.
  No inconsistency results from starting a non-terminating computation because
  you can never inspect the result, whereas if you added the corresponding
  definition as an axiom you might be able to prove something contradictory.
  So we regard the seamless execution of @(':program') mode functions as a
  convenience to the user who might use them to inspect the ACL2 logical world,
  gather data, experiment with constrained formal models by attaching
  executable code to unspecified functions, prototype something to be
  formalized, etc.  In that spirit, we have arranged for @('apply$') to handle
  @(':program') mode functions <i>provided they have badges</i>.  Badges are
  critical because it means that execution of the functions won't ``go outside
  the sandbox.''  However, @('apply$') runs @(':program') mode functions in
  @(tsee safe-mode) to ensure the functional substitutivity of @('apply$'):
  identical calls must always yield identical results.</p>

  <p>It may seem counterintuitive that a top-level @('apply$') of a @(':logic')
  mode function cannot be executed unless @('defwarrant') has succeeded but a
  top-level @('apply$') of a @(':program') mode function can be executed.  As
  noted earlier, the reason is simple: execution of @(':logic') mode functions
  is justified by the axioms of the evaluation theory while no such assurances
  are offered for @(':program') mode functions.</p>

  <h3>Logical Definitions</h3>

  <p>In the following definitions, @('apply$-userfn') is an undefined function
  that is constrained by warrants to describe the tameness requirement and
  behavior of @('apply$') on specific function symbols.  The functions
  @('untame-apply$') and @('untame-ev$') are simply undefined functions for
  giving unspecified values when untame objects are being used.</p>

  @(def apply$)

  @(def apply$-lambda)

  @(def apply$-lambda-logical)

  @(def ev$)

  @(def ev$-list)

  @(def apply$-guard)

  @(def apply$-lambda-guard)

  ")

(defxdoc apply$-guard
  :parents (apply$)
  :short "The guard on @('apply$')"
  :long "<p>The guard on @('(apply$ fn lst)') is @('(apply$-guard fn lst)') which
  is extraordinarily weak.</p>

  @(def apply$-guard)

  <p>where</p>

  @(def apply$-lambda-guard)

  <p>This guard is just strong enough to allow the definitions of the functions
  in the @('apply$') clique to be guard verified.  It does not guarantee that
  @('fn') is tame or well-formed or that @('args') satisfy the guard of
  @('fn').  The last condition is in fact impossible to state given the untyped
  nature of ACL2.  Thus, @('(apply$ fn args)') has to check tameness,
  well-formedness, guard verified, and that @('fn')'s guard is satisfied by
  @('args') when the @('apply$') is executed in the evaluation theory.</p>

  <p>The issue of guards and guard verification of definitions involving
  @('apply$') is further discussed in @(tsee apply$) and in @(tsee
  verify-guards).</p>")

(defxdoc apply$-lambda
  :parents (apply$)
  :short "Used by @('apply$') on @('LAMBDA') objects"
  :long "<p>When @('apply$') is given a @('consp') object as its first argument
  it treats it as a @('LAMBDA') expression and calls this function to apply it.
  This function evaluates the body of the object with @('ev$') under an alist
  binding the formals of the object to the actuals.  See @(tsee apply$) for
  details.</p>")

(defxdoc apply$-lambda-guard
  :parents (apply$)
  :short "The guard on @('apply$-lambda')"
  :long "<p>The guard on @('(apply$-lambda fn lst)') is @('(apply$-lambda-guard
  fn lst)') which is extraordinarily weak.</p>

  @(def apply$-lambda-guard)

  <p>This guard is just strong enough to allow the definitions of the functions
  in the @('apply$') clique to be guard verified.  It does not guarantee that
  @('fn') is @('tame') or well-formed or that @('args') satisfy the guard of
  @('fn').  The last condition is in fact impossible to state given the untyped
  nature of ACL2.  Thus, @('(apply$ fn args)') has to check tameness,
  well-formedness, guard verified and that @('fn')'s guard is satisfied by
  @('args') when the @('apply$') is executed in the evaluation theory.</p>

  <p>The issue of guards and guard verification of definitions involving
  @('apply$') is further discussed in @(tsee apply$) and in @(tsee
  verify-guards).</p>")

(defxdoc apply$-userfn
  :parents (apply$)
  :short "Undefined function used by @('apply$') on non-primitives"
  :long "<p>When @('apply$') is given a non-primitive function symbol it calls
   this function to determine the results of applying that symbol to the given
   arguments.  But this function is undefined.  In the proof theory, its value
   on a given function symbol @('fn') is specified, if at all, by the @(tsee
   warrant) for @('fn') which must be available as a hypothesis in the formula
   being proved.  In the evaluation theory, @('apply$-userfn') has an
   attachment that makes it behave as though all warrants are assumed.  See
   @(tsee apply$) for details.</p>")

(defxdoc architecture-of-the-prover
  :parents (introduction-to-the-theorem-prover)
  :short "A simple overview of how the prover works"
  :long "<p>Six built-in proof techniques are used by ACL2 to decompose the
 goal formula into subgoals.</p>

 <ul>

 <li><i>simplification</i> &mdash; decision procedures and rewriting with
 previously proved rules, but actually including a host of other techniques
 under your control.  Simplification is the only proof technique that can
 reduce a formula to 0 subgoals (i.e., prove it) rather than just transform it
 to other formulas.  The predominant activity in most proofs is simplification.
 There are many ways you can affect what the simplifier does to your formulas.
 Good users spend most of their time thinking about how to control the
 simplifier.</li>

 <li><i>destructor elimination</i> &mdash; getting rid of ``destructor terms''
 like @('(CAR X)') and @('(CDR X)') by replacing a variable, e.g., @('X'), by a
 ``constructor'' term, e.g., @('(CONS A B)').  But you can tell ACL2 about new
 destructor/constructor combinations.</li>

 <li><i>fertilization</i> &mdash; using an equivalence hypothesis by
  substituting one side for the other in the goal.  When under induction, ACL2
  may decide to restrict the substitution as follows, using its so-called
  <i>cross-fertilization</i> heuristic: substitute only into one side of the
  conclusion, thus using an inductive hypothesis in preparation for possible
  generalization in advance of another induction.  Note that
  cross-fertilization is used only when generalization is enabled: with the
  hint @(':do-not '(generalize)'), only full fertilization is applied.</li>

 <li><i>generalization</i> &mdash; replacing a term by a new variable and
 restricting the new variable to have some of the properties of the term.  You
 can control the restrictions imposed on the new variable.  This is a heuristic
 that prepares the goal for another induction.</li>

 <li><i>elimination of irrelevance</i> &mdash; throwing away unnecessary
 hypotheses.  This is a heuristic that prepares the goal for another
 induction.</li>

 <li><i>induction</i> &mdash; selecting an induction scheme to prove a formula.
 Inductions are ``suggested'' by the recursive functions appearing in the
 formula.  But you can control what inductions are suggested by terms.</li>

 </ul>

 <p>But you can add additional techniques, called <i>clause processors</i>.</p>

 <p>The various techniques are tried in turn, with simplification first and
 induction last.  Each technique reports one of three outcomes: it found
 nothing to change (i.e., the technique doesn't <i>apply</i> to that subgoal),
 it decided to abort the proof attempt (typically because there is reason to
 believe the proof is failing), or it decomposed the goal into <i>k</i>
 subgoals.</p>

 <p>The last outcome has a special case: if <i>k</i> is 0 then the technique
 proved the goal.  Whenever <i>k</i> is non-0, the process starts over again
 with simplification on each of the <i>k</i> subgoals.  However, it saves up
 all the subgoals for which induction is the only proof technique left to
 try. That way you see how it performs on every base case and induction step of
 one induction before it launches into another induction.</p>

 <p>It runs until you or one of the proof techniques aborts the proof attempt
 or until all subgoals have been proved.</p>

 <p>Note that if simplification produces a subgoal, that subgoal is
 re-simplified.  This process continues until the subgoal cannot be simplified
 further.  Only then is the next proof technique tried.  Such subgoals are
 said to be <i>stable under simplification</i>.</p>

 <p>While this is happening, the prover prints an English narrative describing
 the process.  Basically, after each goal is printed, the system prints an
 English paragraph that names the next applicable proof technique, gives a
 brief description of what that technique does to the subgoal, and says how
 many new subgoals are produced.  Then each subgoal is dealt with in turn.</p>

 <p>If the proof is successful, you could read this log as a proof of the
 conjecture.  But output from successful proofs is generally never read because
 it is not important to The Method described in @(see
 introduction-to-the-theorem-prover).</p>

 <p>The output of an unsuccessful proof attempt concludes with some <i>key</i>
 <i>checkpoints</i> which usually bear looking at.</p>

 <p>For more information about how ACL2 orchestrates its proof techniques, see
 @(see hints-and-the-waterfall).</p>")

(defxdoc aref1
  :parents (arrays acl2-built-ins)
  :short "Access the elements of a 1-dimensional array"
  :long "@({
  Example Form:
  (aref1 'delta1 a (+ i k))

  General Form:
  (aref1 name alist index)
 })

 <p>where @('name') is a symbol, @('alist') is a 1-dimensional array and
 @('index') is a legal index into @('alist').  This function returns the value
 associated with @('index') in @('alist'), or else the default value of the
 array.  See @(see arrays) for details.</p>

 <p>This function executes in virtually constant time if @('alist') is in fact
 the ``semantic value'' associated with @('name') (see @(see arrays)).  When it
 is not, @('aref1') must do a linear search through @('alist').  In that case
 the correct answer is returned but a <b>slow array</b> comment is printed to
 the comment window.  See @(see slow-array-warning).</p>

 @(def aref1)")

(defxdoc aref2
  :parents (arrays acl2-built-ins)
  :short "Access the elements of a 2-dimensional array"
  :long "@({
  Example Form:
  (aref2 'delta1 a i j)

  General Form:
  (aref2 name alist i j)
 })

 <p>where @('name') is a symbol, @('alist') is a 2-dimensional array and @('i')
 and @('j') are legal indices into @('alist').  This function returns the value
 associated with @('(i . j)') in @('alist'), or else the default value of the
 array.  See @(see arrays) for details.</p>

 <p>This function executes in virtually constant time if @('alist') is in fact
 the ``semantic value'' associated with @('name') (see @(see arrays)).  When it
 is not, @('aref2') must do a linear search through @('alist').  In that case
 the correct answer is returned but a <b>slow array</b> comment is printed to
 the comment window.  See @(see slow-array-warning).</p>

 @(def aref2)")

(defxdoc args
  :parents (documentation)
  :short "@('args'), @(tsee guard), @('type'), @(tsee constraint), etc., of a
  function symbol"
  :long "@({
  Example:
  :args assoc-eq
 })

 <p>@('Args') takes one argument, a symbol which must be the name of a function
 or macro, and prints out some information about it including the formal
 parameters, the @(see guard) expression, the output @(see signature), the
 deduced type, the @(see constraint) (if any), and its @(tsee badge) and @(tsee
 warrant), if any.</p>")

(defxdoc arities-okp
  :parents (acl2-built-ins)
  :short "check the arities of given function symbols"
  :long "@({
  Example:
  (arities-okp '((IF . 3) (CAR . 1) (CONS . 2)) (w state))

  General Form:
  (arities-okp alist w)
 })

 <p>where @('alist') is a @(tsee symbol-alistp) and @('w') is an ACL2 logical
 @(see world).  The alist is presumed to pair @(':')@(tsee logic)-mode function
 symbols with arities.  The result is @('t') or @('nil') according to whether
 each symbol in the alist is a @(':logic')-mode function symbol with the
 associated arity as its @(tsee arity) in @('w').  See @(see
 well-formedness-guarantee).</p>

 @(def arities-okp)")

(defxdoc arity
  :parents (acl2-built-ins)
  :short "number of arguments of a function symbol"
  :long "@({
  Examples:
  (arity 'IF (w state))
  (arity '(LAMBDA (X) (CONS X X)) (w state))

  General Form:
  (arity fn w)
 })

 <p>where @('fn') is a function symbol or a lambda expression and @('w') is an
 ACL2 logical @(see world).  The result is the number of arguments the function
 or lambda expression takes, or @('nil') if the function symbol is not defined
 in @('w').</p>

 See @(see arity+) for a variant of @('arity') with a stronger @(see guard).")

(defxdoc array1p
  :parents (arrays acl2-built-ins)
  :short "Recognize a 1-dimensional array"
  :long "@({
  Example Form:
  (array1p 'delta1 a)

  General Form:
  (array1p name alist)
 })

 <p>where @('name') and @('alist') are arbitrary objects.  This function
 returns @('t') if @('alist') is a 1-dimensional ACL2 array.  Otherwise it
 returns @('nil').  The function operates in constant time if @('alist') is the
 semantic value of @('name').  See @(see arrays).</p>

 @(def array1p)")

(defxdoc array2p
  :parents (arrays acl2-built-ins)
  :short "Recognize a 2-dimensional array"
  :long "@({
  Example Form:
  (array2p 'delta1 a)

  General Form:
  (array2p name alist)
 })

 <p>where @('name') and @('alist') are arbitrary objects.  This function
 returns @('t') if @('alist') is a 2-dimensional ACL2 array.  Otherwise it
 returns @('nil').  The function operates in constant time if @('alist') is the
 semantic value of @('name').  See @(see arrays).</p>

 @(def array2p)")

(defxdoc arrays
  :parents (programming)
  :short "ACL2 arrays and operations on them"
  :long "<p>Below we begin a detailed presentation of ACL2 arrays.  ACL2's
 single-threaded objects (see @(see stobj)) provide a similar functionality
 that is generally more efficient when there are updates (writes), but is also
 more restrictive.</p>

 <p>See @(see arrays-example) for a brief introduction illustrating the use of
 ACL2 arrays.</p>

 <p>ACL2 provides relatively efficient 1- and 2-dimensional arrays.  Arrays are
 awkward to provide efficiently in an applicative language because the
 programmer rightly expects to be able to ``modify'' an array object with the
 effect of changing the behavior of the element accessing function on that
 object.  This, of course, does not make any sense in an applicative setting.
 The element accessing function is, after all, a function, and its behavior on
 a given object is immutable.  To ``modify'' an array object in an applicative
 setting we must actually produce a new array object.  Arranging for this to be
 done efficiently is a challenge to the implementors of the language.  In
 addition, the programmer accustomed to the von Neumann view of arrays must
 learn how to use immutable applicative arrays efficiently.</p>

 <p>In this note we explain 1-dimensional arrays.  In particular, we explain
 briefly how to create, access, and ``modify'' them, how they are implemented,
 and how to program with them.  2-dimensional arrays are dealt with by
 analogy.</p>

 <h3>The Logical Description of ACL2 Arrays</h3>

 <p>An ACL2 1-dimensional array is an object that associates arbitrary objects
 with certain integers, called ``indices.'' Every array has a dimension,
 @('dim'), which is a positive integer.  The indices of an array are the
 consecutive integers from @('0') through @('dim-1').  To obtain the object
 associated with the index @('i') in an array @('a'), one uses @('(aref1 name a
 i)').  @('Name') is a symbol that is irrelevant to the semantics of @(tsee
 aref1) but affects the speed with which it computes.  We will talk more about
 array ``names'' later.  To produce a new array object that is like @('a') but
 which associates @('val') with index @('i'), one uses @('(aset1 name a i
 val)').</p>

 <p>An ACL2 1-dimensional array is actually an alist.  There is no special ACL2
 function for creating arrays; they are generally built with the standard list
 processing functions @(tsee list) and @(tsee cons).  However, there is a
 special ACL2 function, called @(tsee compress1), for speeding up access to the
 elements of such an alist.  We discuss @(tsee compress1) later.</p>

 <p>One element of the alist must be the ``header'' of the array.  The @(see
 header) of a 1-dimensional array with dimension @('dim') is of the form:</p>

 @({
  (:HEADER :DIMENSIONS (dim)
           :MAXIMUM-LENGTH max
           :DEFAULT obj ; optional
           :NAME name   ; optional
           :ORDER order ; optional values are < (the default), >, or :none/nil
           ).
 })

 <p>@('Obj') may be any object and is called the ``default value'' of the
 array.  @(tsee Max) must be an integer greater than @('dim').  @('Name') must
 be a symbol.  The @(':')@(tsee default) and @(':name') entries are optional;
 if @(':')@(tsee default) is omitted, the default value is @('nil').  The
 function @(tsee header), when given a name and a 1- or 2-dimensional array,
 returns the @(see header) of the array.  The functions @(tsee dimensions),
 @(tsee maximum-length), and @(tsee default) are similar and return the
 corresponding fields of the @(see header) of the array.  The role of the
 @(':')@(tsee dimensions) field is obvious: it specifies the legal indices into
 the array.  The roles played by the @(':')@(tsee maximum-length) and
 @(':')@(tsee default) fields are described below.</p>

 <p>Aside from the @(see header), the other elements of the alist must each be
 of the form @('(i . val)'), where @('i') is an integer and @('0 <= i < dim'),
 and @('val') is an arbitrary object.</p>

 <p>The @(':order') field of the header is ignored for 2-dimensional arrays.
 For 1-dimensional arrays, it specifies the order of keys (@('i'), above) when
 the array is compressed as with @(tsee compress1), as described below.  An
 @(':order') of @(':none') or @('nil') specifies no reordering of the alist by
 @(tsee compress1), and an order of @('>') specifies reordering by @(tsee
 compress1) so that keys are in descending order.  Otherwise, the alist is
 reordered by @(tsee compress1) so that keys are in ascending order.</p>

 <p>@('(Aref1 name a i)') is @(see guard)ed so that @('name') must be a symbol,
 @('a') must be an array and @('i') must be an index into @('a').  The value of
 @('(aref1 name a i)') is either @('(cdr (assoc i a))') or else is the default
 value of @('a'), depending on whether there is a pair in @('a') whose @(tsee
 car) is @('i').  Note that @('name') is irrelevant to the value of an @(tsee
 aref1) expression.  You might @(':pe aref1') to see how simple the definition
 is.</p>

 <p>@('(Aset1 name a i val)') is @(see guard)ed analogously to the @(tsee
 aref1) expression.  The value of the @(tsee aset1) expression is essentially
 @('(cons (cons i val) a)').  Again, @('name') is irrelevant.  Note @('(aset1
 name a i val)') is an array, @('a''), with the property that @('(aref1 name a'
 i)') is @('val') and, except for index @('i'), all other indices into @('a'')
 produce the same value as in @('a').  Note also that if @('a') is viewed as an
 alist (which it is) the pair ``binding'' @('i') to its old value is in @('a'')
 but ``covered up'' by the new pair.  Thus, the length of an array grows by one
 when @(tsee aset1) is done.</p>

 <p>Because @(tsee aset1) covers old values with new ones, an array produced by
 a sequence of @(tsee aset1) calls may have many irrelevant pairs in it.  The
 function @(tsee compress1) can remove these irrelevant pairs.  Thus,
 @('(compress1 name a)') returns an array that is equivalent (vis-a-vis @(tsee
 aref1)) to @('a') but which may be shorter.  For technical reasons, the alist
 returned by @(tsee compress1) may also list the pairs in a different order
 than listed in @('a').</p>

 <p>To prevent arrays from growing excessively long due to repeated @(tsee
 aset1) operations, @(tsee aset1) essentially calls @(tsee compress1) on the
 new alist whenever the length of the new alist exceeds the @(':')@(tsee
 maximum-length) entry, @(tsee max), in the @(see header) of the array.  See
 the definition of @(tsee aset1) (for example by using @(':')@(tsee pe)).  This
 is primarily just a mechanism for freeing up @(tsee cons) space consumed while
 doing @(tsee aset1) operations.  Note however that this @(tsee compress1) call
 is replaced by a hard error if the header specifies an @(':order') of
 @(':none') or @('nil').</p>

 <p>This completes the logical description of 1-dimensional arrays.
 2-dimensional arrays are analogous.  The @(':')@(tsee dimensions) entry of the
 @(see header) of a 2-dimensional array should be @('(dim1 dim2)').  A pair of
 indices, @('i') and @('j'), is legal iff @('0 <= i < dim1') and @('0 <= j <
 dim2').  The @(':')@(tsee maximum-length) must be greater than @('dim1*dim2').
 @(tsee Aref2), @(tsee aset2), and @(tsee compress2) are like their
 counterparts but take an additional @('index') argument.  Finally, the pairs
 in a 2-dimensional array are of the form @('((i . j) . val)').</p>

 <h3>The Implementation of ACL2 Arrays</h3>

 <p>Very informally speaking, the function @(tsee compress1) ``creates'' an
 ACL2 array that provides fast access, while the function @(tsee aref1)
 ``maintains'' fast access.  We now describe this informal idea more
 carefully.</p>

 <p>@(tsee Aref1) is essentially @(tsee assoc).  If @(tsee aref1) were
 implemented naively the time taken to access an array element would be linear
 in the dimension of the array and the number of ``assignments'' to it (the
 number of @(tsee aset1) calls done to create the array from the initial
 alist).  This is intolerable; arrays are ``supposed'' to provide constant-time
 access and change.</p>

 <p>The apparently irrelevant names associated with ACL2 arrays allow us to
 provide constant-time access and change when arrays are used in
 ``conventional'' ways.  The implementation of arrays makes it clear what we
 mean by ``conventional.''</p>

 <p>Recall that array names are symbols.  Behind the scenes, ACL2 associates
 two objects with each ACL2 array name.  The first object is called the
 ``semantic value'' of the name and is an alist.  The second object is called
 the ``raw lisp array'' and is a Common Lisp array.</p>

 <p>When @('(compress1 name alist)') builds a new alist, @('a''), it sets the
 semantic value of @('name') to that new alist.  Furthermore, it writes into a
 Common Lisp array all of the index/value pairs of @('a''), initializing
 unassigned indices with the default value.  In general this is a new array,
 which becomes the raw lisp array of @('name').  However, if a raw lisp array
 is already associated with @('name') and is at least as long as the dimension
 specified in the @(see header), then that array is reused and all indices out
 of range are ignored.  (Such reuse can be avoided; see @(see flush-compress)
 for how to remove the existing association of a raw lisp array with a name.)
 Either way, @(tsee compress1) then returns @('a''), the semantic value, as its
 result, as required by the definition of @(tsee compress1).</p>

 <p>When @('(aref1 name a i)') is invoked, @(tsee aref1) first determines
 whether the semantic value of @('name') is @('a') (i.e., is @(tsee eq) to the
 alist @('a')).  If so, @(tsee aref1) can determine the @('i')th element of
 @('a') by invoking Common Lisp's @('aref') function on the raw lisp array
 associated with name.  Note that no linear search of the alist @('a') is
 required; the operation is done in constant time and involves retrieval of two
 global variables, an @(tsee eq) test and @('jump'), and a raw lisp array
 access.  In fact, an ACL2 array access of this sort is about 5 times slower
 than a C array access.  On the other hand, if @('name') has no semantic value
 or if it is different from @('a'), then @(tsee aref1) determines the answer by
 linear search of @('a') as suggested by the @('assoc-like') definition of
 @(tsee aref1).  Thus, @(tsee aref1) always returns the axiomatically specified
 result.  It returns in constant time if the array being accessed is the
 current semantic value of the name used.  The ramifications of this are
 discussed after we deal with @(tsee aset1).</p>

 <p>When @('(aset1 name a i val)') is invoked, @(tsee aset1) does two @(tsee
 cons)es to create the new array.  Call that array @('a'').  It will be
 returned as the answer.  (In this discussion we ignore the case in which
 @(tsee aset1) does a @(tsee compress1).)  However, before returning, @(tsee
 aset1) determines if @('name')'s semantic value is @('a').  If so, it makes
 the new semantic value of @('name') be @('a'') and it smashes the raw lisp
 array of @('name') with @('val') at index @('i'), before returning @('a'') as
 the result.  Thus, after doing an @(tsee aset1) and obtaining a new semantic
 value @('a''), all @(tsee aref1)s on that new array will be fast.  Any @(tsee
 aref1)s on the old semantic value, @('a'), will be slow.</p>

 <p>To understand the performance implications of this design, consider the
 chronological sequence in which ACL2 (Common Lisp) evaluates expressions:
 basically inner-most first, left-to-right, call-by-value.  An array use, such
 as @('(aref1 name a i)'), is ``fast'' (constant-time) if the alist supplied,
 @('a'), is the value returned by the most recently executed @(tsee compress1)
 or @(tsee aset1) on the name supplied.  In the functional expression of
 ``conventional'' array processing, all uses of an array are fast.</p>

 <p>The @(':name') field of the @(see header) of an array is completely
 irrelevant.  Our convention is to store in that field the symbol we mean to
 use as the name of the raw lisp array.  But no ACL2 function inspects
 @(':name') and its primary value is that it allows the user, by inspecting the
 semantic value of the array &mdash; the alist &mdash; to recall the name of
 the raw array that probably holds that value.  We say ``probably'' since there
 is no enforcement that the alist was compressed under the name in the @(see
 header) or that all @('aset')s used that name.  Such enforcement would be
 inefficient.</p>

 <h3>Some Programming Examples</h3>

 <p>In the following examples we will use ACL2 ``global variables'' to hold
 several arrays.  See @(see @), and see @(see assign).</p>

 <p>Let the @(tsee state) global variable @('a') be the 1-dimensional
 compressed array of dimension @('5') constructed below.</p>

 @({
  ACL2 !>(assign a (compress1 'demo
                              '((:header :dimensions (5)
                                         :maximum-length 15
                                         :default uninitialized
                                         :name demo)
                                (0 . zero))))
 })

 <p>Then @('(aref1 'demo (@ a) 0)') is @('zero') and @('(aref1 'demo (@ a) 1)')
 is @('uninitialized').</p>

 <p>Now execute</p>

 @({
  ACL2 !>(assign b (aset1 'demo (@ a) 1 'one))
 })

 <p>Then @('(aref1 'demo (@ b) 0)') is @('zero') and @('(aref1 'demo (@ b) 1)')
 is @('one').</p>

 <p>All of the @(tsee aref1)s done so far have been ``fast.''</p>

 <p>Note that we now have two array objects, one in the global variable @('a')
 and one in the global variable @('b').  @('B') was obtained by assigning to
 @('a').  That assignment does not affect the alist @('a') because this is an
 applicative language.  Thus, @('(aref1 'demo (@ a) 1)') must <b>still</b> be
 @('uninitialized').  And if you execute that expression in ACL2 you will see
 that indeed it is.  However, a rather ugly comment is printed, namely that
 this array access is ``slow.''  The reason it is slow is that the raw lisp
 array associated with the name @('demo') is the array we are calling @('b').
 To access the elements of @('a'), @(tsee aref1) must now do a linear search.
 Any reference to @('a') as an array is now ``unconventional;'' in a
 conventional language like Ada or Common Lisp it would simply be impossible to
 refer to the value of the array before the assignment that produced our
 @('b').</p>

 <p>Now let us define a function that counts how many times a given object,
 @('x'), occurs in an array.  For simplicity, we will pass in the name and
 highest index of the array:</p>

 @({
  ACL2 !>(defun cnt (name a i x)
           (declare (xargs :guard
                           (and (array1p name a)
                                (integerp i)
                                (>= i -1)
                                (< i (car (dimensions name a))))
                           :mode :logic
                           :measure (nfix (+ 1 i))))
           (cond ((zp (1+ i)) 0) ; return 0 if i is at most -1
                 ((equal x (aref1 name a i))
                  (1+ (cnt name a (1- i) x)))
                 (t (cnt name a (1- i) x))))
 })

 <p>To determine how many times @('zero') appears in @('(@ b)') we can
 execute:</p>

 @({
  ACL2 !>(cnt 'demo (@ b) 4 'zero)
 })

 <p>The answer is @('1').  How many times does @('uninitialized') appear in
 @('(@ b)')?</p>

 @({
  ACL2 !>(cnt 'demo (@ b) 4 'uninitialized)
 })

 <p>The answer is @('3'), because positions @('2'), @('3') and @('4') of the
 array contain that default value.</p>

 <p>Now imagine that we want to assign @(''two') to index @('2') and then count
 how many times the 2nd element of the array occurs in the array.  This
 specification is actually ambiguous.  In assigning to @('b') we produce a new
 array, which we might call @('c').  Do we mean to count the occurrences in
 @('c') of the 2nd element of @('b') or the 2nd element of @('c')?  That is, do
 we count the occurrences of @('uninitialized') or the occurrences of @('two')?
 If we mean the former the correct answer is @('2') (positions @('3') and
 @('4') are @('uninitialized') in @('c')); if we mean the latter, the correct
 answer is @('1') (there is only one occurrence of @('two') in @('c')).</p>

 <p>Below are ACL2 renderings of the two meanings, which we call @('[former]')
 and @('[latter]').  (Warning: Our description of these examples, and of an
 example @('[fast former]') that follows, assumes that only one of these three
 examples is actually executed; for example, they are not executed in sequence.
 See ``A Word of Warning'' below for more about this issue.)</p>

 @({
  (cnt 'demo (aset1 'demo (@ b) 2 'two) 4 (aref1 'demo (@ b) 2))  ; [former]

  (let ((c (aset1 'demo (@ b) 2 'two)))                           ; [latter]
    (cnt 'demo c 4 (aref1 'demo c 2)))
 })

 <p>Note that in @('[former]') we create @('c') in the second argument of the
 call to @('cnt') (although we do not give it a name) and then refer to @('b')
 in the fourth argument.  This is unconventional because the second reference
 to @('b') in @('[former]') is no longer the semantic value of @('demo').
 While ACL2 computes the correct answer, namely @('2'), the execution of the
 @(tsee aref1) expression in @('[former]') is done slowly.</p>

 <p>A conventional rendering with the same meaning is</p>

 @({
  (let ((x (aref1 'demo (@ b) 2)))                           ; [fast former]
    (cnt 'demo (aset1 'demo (@ b) 2 'two) 4 x))
 })

 <p>which fetches the 2nd element of @('b') before creating @('c') by
 assignment.  It is important to understand that @('[former]') and @('[fast
 former]') mean exactly the same thing: both count the number of occurrences of
 @('uninitialized') in @('c').  Both are legal ACL2 and both compute the same
 answer, @('2').  Indeed, we can symbolically transform @('[fast former]') into
 @('[former]') merely by substituting the binding of @('x') for @('x') in the
 body of the @(tsee let).  But @('[fast former]') can be evaluated faster than
 @('[former]') because all of the references to @('demo') use the then-current
 semantic value of @('demo'), which is @('b') in the first line and @('c')
 throughout the execution of the @('cnt') in the second line.  @('[Fast
 former]') is the preferred form, both because of its execution speed and its
 clarity.  If you were writing in a conventional language you would have to
 write something like @('[fast former]') because there is no way to refer to
 the 2nd element of the old value of @('b') after smashing @('b') unless it had
 been saved first.</p>

 <p>We turn now to @('[latter]').  It is both clear and efficient.  It creates
 @('c') by assignment to @('b') and then it fetches the 2nd element of @('c'),
 @('two'), and proceeds to count the number of occurrences in @('c').  The
 answer is @('1').  @('[Latter]') is a good example of typical ACL2 array
 manipulation: after the assignment to @('b') that creates @('c'), @('c') is
 used throughout.</p>

 <p>It takes a while to get used to this because most of us have grown
 accustomed to the peculiar semantics of arrays in conventional languages.  For
 example, in raw lisp we might have written something like the following,
 treating @('b') as a ``global variable'':</p>

 @({
  (cnt 'demo (aset 'demo b 2 'two) 4 (aref 'demo b 2))
 })

 <p>which sort of resembles @('[former]') but actually has the semantics of
 @('[latter]') because the @('b') from which @('aref') fetches the 2nd element
 is not the same @('b') used in the @('aset')!  The array @('b') is destroyed
 by the @('aset') and @('b') henceforth refers to the array produced by the
 @('aset'), as written more clearly in @('[latter]').</p>

 <p>A Word of Warning: Users must exercise care when experimenting with
 @('[former]'), @('[latter]') and @('[fast former]').  Suppose you have just
 created @('b') with the assignment shown above,</p>

 @({
  ACL2 !>(assign b (aset1 'demo (@ a) 1 'one))
 })

 <p>If you then evaluate @('[former]') in ACL2 it will complain that the @(tsee
 aref1) is slow and compute the answer, as discussed.  Then suppose you
 evaluate @('[latter]') in ACL2.  From our discussion you might expect it to
 execute fast &mdash; i.e., issue no complaint.  But in fact you will find that
 it complains repeatedly.  The problem is that the evaluation of @('[former]')
 changed the semantic value of @('demo') so that it is no longer @('b').  To
 try the experiment correctly you must make @('b') be the semantic value of
 @('demo') again before the next example is evaluated.  One way to do that is
 to execute</p>

 @({
  ACL2 !>(assign b (compress1 'demo (@ b)))
 })

 <p>before each expression.  Because of issues like this it is often hard to
 experiment with ACL2 arrays at the top-level.  We find it easier to write
 functions that use arrays correctly and efficiently than to so use them
 interactively.</p>

 <p>This last assignment also illustrates a very common use of @(tsee
 compress1).  While it was introduced as a means of removing irrelevant pairs
 from an array built up by repeated assignments, it is actually most useful as
 a way of insuring fast access to the elements of an array.</p>

 <p>Many array processing tasks can be divided into two parts.  During the
 first part the array is built.  During the second part the array is used
 extensively but not modified.  If your @(see programming) task can be so
 divided, it might be appropriate to construct the array entirely with list
 processing, thereby saving the cost of maintaining the semantic value of the
 name while few references are being made.  Once the alist has stabilized, it
 might be worthwhile to treat it as an array by calling @(tsee compress1),
 thereby gaining constant time access to it.</p>

 <p>ACL2's theorem prover uses this technique in connection with its
 implementation of the notion of whether a @(see rune) is @(see disable)d or
 not.  Associated with every @(see rune) is a unique integer @('index'), called
 its ``nume.''  When each rule is stored, the corresponding nume is stored as a
 component of the rule.  @(see Theories) are lists of @(see rune)s and
 membership in the ``current theory'' indicates that the corresponding rule is
 @(see enable)d.  But these lists are very long and membership is a linear-time
 operation.  So just before a proof begins we map the list of @(see rune)s in
 the current theory into an alist that pairs the corresponding numes with
 @('t').  Then we compress this alist into an array.  Thus, given a rule we can
 obtain its nume (because it is a component) and then determine in constant
 time whether it is @(see enable)d.  The array is never modified during the
 proof, i.e., @(tsee aset1) is never used in this example.  From the logical
 perspective this code looks quite odd: we have replaced a linear-time
 membership test with an apparently linear-time @(tsee assoc) after going to
 the trouble of mapping from a list of @(see rune)s to an alist of numes.  But
 because the alist of numes is an array, the ``apparently linear-time @(tsee
 assoc)'' is more apparent than real; the operation is constant-time.</p>")

(defxdoc arrays-example
  :parents (arrays)
  :short "An example illustrating ACL2 arrays"
  :long "<p>The example below illustrates the use of ACL2 arrays.  It is not,
 of course, a substitute for the detailed explanations provided elsewhere (see
 @(see arrays), including subtopics).</p>

 @({
  ACL2 !>(defun defarray (name size initial-element)
           (compress1 name
                      (cons (list :HEADER
                                  :DIMENSIONS (list size)
                                  :MAXIMUM-LENGTH (1+ size)
                                  :DEFAULT initial-element
                                  :NAME name)
                            nil)))

  Since DEFARRAY is non-recursive, its admission is trivial.  We observe
  that the type of DEFARRAY is described by the theorem
  (AND (CONSP (DEFARRAY NAME SIZE INITIAL-ELEMENT))
       (TRUE-LISTP (DEFARRAY NAME SIZE INITIAL-ELEMENT))).
  We used the :type-prescription rule COMPRESS1.

  Summary
  Form:  ( DEFUN DEFARRAY ...)
  Rules: ((:TYPE-PRESCRIPTION COMPRESS1))
  Warnings:  None
  Time:  0.02 seconds (prove: 0.00, print: 0.02, other: 0.00)
   DEFARRAY
  ACL2 !>(assign my-ar (defarray 'a1 5 17))
   ((:HEADER :DIMENSIONS (5)
             :MAXIMUM-LENGTH 6 :DEFAULT 17 :NAME A1))
  ACL2 !>(aref1 'a1 (@ my-ar) 3)
  17
  ACL2 !>(aref1 'a1 (@ my-ar) 8)

  ACL2 Error in TOP-LEVEL:  The guard for the function symbol AREF1,
  which is
  (AND (ARRAY1P NAME L) (INTEGERP N) (>= N 0) (< N (CAR (DIMENSIONS NAME L)))),
  is violated by the arguments in the call (AREF1 'A1 '(#) 8).

  ACL2 !>(assign my-ar (aset1 'a1 (@ my-ar) 3 'xxx))
   ((3 . XXX)
    (:HEADER :DIMENSIONS (5)
             :MAXIMUM-LENGTH 6 :DEFAULT 17 :NAME A1))
  ACL2 !>(aref1 'a1 (@ my-ar) 3)
  XXX
  ACL2 !>(aset1 'a1 (@ my-ar) 3 'yyy) ; BAD: (@ my-ar) now points to
                                      ;      an old copy of the array!
  ((3 . YYY)
   (3 . XXX)
   (:HEADER :DIMENSIONS (5)
            :MAXIMUM-LENGTH 6 :DEFAULT 17 :NAME A1))
  ACL2 !>(aref1 'a1 (@ my-ar) 3) ; Because of "BAD" above, the array
                                 ; access is done using assoc rather
                                 ; than Lisp aref, hence is slower;
                                 ; but the answer is still correct,
                                 ; reflecting the value in (@ my-ar),
                                 ; which was not changed above.

  **********************************************************
  Slow Array Access!  A call of AREF1 on an array named
  A1 is being executed slowly.  See :DOC slow-array-warning
  **********************************************************

  XXX
  ACL2 !>
 })")

(defxdoc aset1
  :parents (arrays acl2-built-ins)
  :short "Set the elements of a 1-dimensional array"
  :long "@({
  Example Form:
  (aset1 'delta1 a (+ i k) 27)

  General Form:
  (aset1 name alist index val)
 })

 <p>where @('name') is a symbol, @('alist') is a 1-dimensional array named
 @('name'), @('index') is a legal index into @('alist'), and @('val') is an
 arbitrary object.  See @(see arrays) for details.  Roughly speaking this
 function ``modifies'' @('alist') so that the value associated with @('index')
 is @('val').  More precisely, it returns a new array, @('alist''), of the same
 name and dimension as @('alist') that, under @(tsee aref1), is everywhere
 equal to @('alist') except at @('index') where the result is @('val').  That
 is, @('(aref1 name alist' i)') is @('(aref1 name alist i)') for all legal
 indices @('i') except @('index'), where @('(aref1 name alist' i)') is
 @('val').</p>

 <p>In order to ``modify'' @('alist'), @('aset1') @(tsee cons)es a new pair
 onto the front.  If the length of the resulting alist exceeds the @(':')@(tsee
 maximum-length) entry in the array @(see header), @('aset1') compresses the
 array as with @(tsee compress1).</p>

 <p>It is generally expected that the ``semantic value'' of @('name') will be
 @('alist') (see @(see arrays)).  This function operates in virtually constant
 time whether this condition is true or not (unless the @(tsee compress1)
 operation is required).  But the value returned by this function cannot be
 used efficiently by subsequent @('aset1') operations unless @('alist') is the
 semantic value of @('name') when @('aset1') is executed.  Thus, if the
 condition is not true, @('aset1') prints a <b>slow array</b> warning to the
 comment window.  See @(see slow-array-warning).</p>

 <p>Note that @(tsee aset1) is marked as having @(tsee invariant-risk), which
 can affect the execution of @(':')@(tsee program)-mode functions.  To get
 around this problem (but only with great care!), see @(see aset1-trusted).</p>

 @(def aset1)")

(defxdoc aset1-trusted
  :parents (arrays acl2-built-ins aset1)
  :short "Set the elements of a 1-dimensional array without @(see
 invariant-risk)"
  :long "@({
 Example Form:
 (aset1-trusted 'delta1 a (+ i k) 27)

 General Form:
 (aset1-trusted name alist index val)
 })

 <p>This utility is identical to @(tsee aset1); in fact, it has the same guard.
 The difference is that it does not carry @(see invariant-risk).  Because of
 that, functions that call @('aset1-trusted') may suffer from invariant-risk
 but not be noted by the system as carrying invariant-risk.  Therefore,
 @('aset1-trusted') it is @(see untouchable) and should be used with great
 care.  If your system consists of @(':')@(tsee logic)-mode functions, then
 there is no reason to use @('aset1-trusted'), because only @(':')@(tsee
 program)-mode functions truly carry invariant-risk.</p>

 @(def aset1-trusted)")

(defxdoc aset2
  :parents (arrays acl2-built-ins)
  :short "Set the elements of a 2-dimensional array"
  :long "@({
  Example Form:
  (aset2 'delta1 a i j 27)

  General Form:
  (aset2 name alist i j val)
 })

 <p>where @('name') is a symbol, @('alist') is a 2-dimensional array named
 @('name'), @('i') and @('j') are legal indices into @('alist'), and @('val')
 is an arbitrary object.  See @(see arrays) for details.  Roughly speaking this
 function ``modifies'' @('alist') so that the value associated with @('(i
 . j)') is @('val').  More precisely, it returns a new array, @('alist''), of
 the same name and dimension as @('alist') that, under @(tsee aref2), is
 everywhere equal to @('alist') except at @('(i . j)') where the result is
 @('val').  That is, @('(aref2 name alist' x y)') is @('(aref2 name alist x
 y)') for all legal indices @('x') @('y') except @('i') and @('j') where
 @('(aref2 name alist' i j)') is @('val').</p>

 <p>In order to ``modify'' @('alist'), @('aset2') @(tsee cons)es a new pair
 onto the front.  If the length of the resulting @('alist') exceeds the
 @(':')@(tsee maximum-length) entry in the array @(see header), @('aset2')
 compresses the array as with @(tsee compress2).</p>

 <p>It is generally expected that the ``semantic value'' of @('name') will be
 @('alist') (see @(see arrays)).  This function operates in virtually constant
 time whether this condition is true or not (unless the @(tsee compress2)
 operation is required).  But the value returned by this function cannot be
 used efficiently by subsequent @('aset2') operations unless @('alist') is the
 semantic value of @('name') when @('aset2') is executed.  Thus, if the
 condition is not true, @('aset2') prints a <b>slow array</b> warning to the
 comment window.  See @(see slow-array-warning).</p>

 @(def aset2)")

(defxdoc ash
  :parents (numbers acl2-built-ins)
  :short "Arithmetic shift operation"
  :long "<p>@('(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').</p>

 <p>The @(see guard) for @('ash') requires that its arguments are integers.</p>

 <p>@('Ash') is a Common Lisp function.  See any Common Lisp documentation for
 more information.</p>

 @(def ash)")

(defxdoc assert$
  :parents (errors acl2-built-ins)
  :short "Cause a hard error if the given test is false"
  :long "@({
  General Form:
  (assert$ test form)
 })

 <p>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 @(tsee illegal), which has a @(see 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').</p>

 <p>See also @(tsee assert*).  Both @(tsee assert$) and @(tsee assert*) create
 a @(see guard) proof obligation (when used in a definition made in @(tsee
 logic)-mode).  However, @('assert$') checks the assertion at runtime, while
 @('assert*') does not.</p>

 <p>Also see @(see assert-event) for an assertion-checking utility that is an
 @(see event).</p>")

(defxdoc assert*
  :parents (errors acl2-built-ins)
  :short "Create a @(see guard) proof obligation that given test holds"
  :long "@({
  General Form:
  (assert* test form)
 })

 <p>where @('test') returns a single value and @('form') is arbitrary.
 Semantically, this call of @('assert*') is equivalent to @('form').  However,
 a @(see guard) proof obligation is created that @('test') holds, when used in
 a definition made in @(tsee logic)-mode.</p>

 <p>For a related utility, see @(see assert$).  Both @('assert$') and
 @('assert*') create a @(see guard) proof obligation (when used in a definition
 made in @(tsee logic)-mode).  However, @('assert$') checks the assertion at
 runtime, while @('assert*') does not.</p>

 <p>Also see @(see assert-event) for an assertion-checking utility that is an
 @(see event).</p>

 @(def assert*)")

(defxdoc assert-event
  :parents (events errors)
  :short "Assert that a given form returns a non-@('nil') value"
  :long "<p>@('Assert-event') provides a flexible way to check that evaluation
 of an expression returns a non-@('nil') value, causing an error otherwise.
 Calls of @('assert-event') are @(see event) forms; thus, they may occur in
 @(see books) as well as @(tsee encapsulate) and @(tsee progn) events.  See
 also @(see assert!) and @(see assert!-stobj) for simple interfaces to
 @('assert-event').  See @(see assert$) and @(see assert*) for
 assertion-checking utilities to use in programs.</p>

 <p>Basic calls of @('assert-event') will take just one argument, called an
 ``assertion'', which is a form that evaluates to a single value that is not a
 @(see stobj).  The following log shows a successful invocation &mdash; one
 where the assertion evaluates to a non-@('nil') value.</p>

 @({
 ACL2 !>(assert-event (equal (+ 3 4) 7))
  :PASSED
 ACL2 !>
 })

 <p>Such a use of @('assert-event') will probably suffice for most users, that
 is, where the form evaluates to a single non-stobj value and there are no
 keyword arguments.  The keyword arguments, which are optional and discussed
 below, extend that functionality, for example: multiple values are permitted
 by keyword @(':stobjs-out'), and keyword @(':on-skip-proofs') can override the
 default behavior of ignoring assertions when proofs are being skipped.</p>

 @({
 General Form:
 (assert-event assertion
               :event event           ; default nil
               ;; evaluated keyword arguments:
               :ctx                   ; default 'assert-event
               :msg msg               ; default t
               :on-skip-proofs sp     ; default nil
               :safe-mode safe-mode   ; default :same
               :stobjs-out stobjs-out ; default nil
               )
 })

 <p>where @('assertion') and @('event') are not evaluated but all the other
 arguments are evaluated, with the defaults shown above corresponding to values
 after evaluation.</p>

 <p>The following example illustrates all of the keyword arguments, which are
 documented below.</p>

 @({
 (assert-event (mv (equal (+ 3 4) 7) state)
               :event (defun f (x) (cons x x))
               :ctx '(assert-event . <some-mv>)
               :msg (msg "Oops, I forgot what ~x0+~x1 is!" 3 4)
               :on-skip-proofs t
               :safe-mode nil
               :stobjs-out '(nil state))
 })

 <p>@('Assert-event') is a macro whose expansion directly produces a call of
 the primitive event, @('value-triple'), where: if a call of @('assert-event')
 specifies @(':msg msg'), then the corresponding call of @('value-triple')
 specifies @(':check (or msg t)').  But unlike @('value-triple'),
 @('assert-event') can specify an event to evaluate when the assertion has
 non-@('nil') value, using the @(':event') keyword.  (You can get a sense of
 the @('value-triple') call generated from an @('assert-event') call by using
 @(':')@(tsee trans1) on the @('assert-event') form.)  The remaining keyword
 arguments of @('assert-event') are also arguments of @('value-triple').  Here
 is a brief summary of the keyword arguments, but <b>NOTE</b>: see @(see
 value-triple) for more detailed explanations of keywords other than
 @(':EVENT').</p>

 <p>@(':EVENT event') (default @('nil')): When @('event') is not @('nil'), it
 should be an @(see event), that is, a form that may be in a book or a call of
 @(tsee encapsulate) or @(tsee progn).  If the assertion evaluates to a
 non-@('nil') value (or to multiple values where the first value is not a stobj
 and is non-@('nil'); see @(':STOBJS-OUT') below), then @('event') is
 evaluated; otherwise the evaluation results in an error.</p>

 <p>@(':CTX ctx') (default: @(''assert-event')): context for error messages.</p>

 <p>@(':MSG msg') (default: @('t')): message to print when there is an
 error (equivalent to keyword argument @(':CHECK') of @(tsee
 value-triple)).</p>

 <p>@(':ON-SKIP-PROOFS sp') (default: @('nil')): supply @('t') to evaluate the
 assertion even when skipping proofs (i.e., during @(tsee include-book) or the
 second pass of an @(tsee encapsulate) event, or after invoking @(tsee
 set-ld-skip-proofsp) to skip proofs).</p>

 <p>@(':SAFE-MODE safe-mode') (default: @(':same')): provides backward
 compatibility, but is probably best ignored.</p>

 <p>@(':STOBJS-OUT stobjs-out') (default: @('nil')): specify @(':auto') to
 allow any return, even with multiple values provided the first return value is
 not a @(see stobj); or specify a list starting with @('nil'), corresponding to
 the multiple values returned, with stobjs in stobj positions and @('nil')
 elsewhere.  A @('stobjs-out') of @('nil') is treated as @('(nil)').  The first
 return value is the one checked to be non-@('nil') with one exception: when an
 @(see error-triple) @('(mv erp val state)') is returned, @('erp') must be
 @('nil') and it is @('val') that is checked to be non-@('nil').</p>")

(defxdoc assign
  :parents (programming-with-state acl2-built-ins)
  :short "Assign to a global variable in @(tsee state)"
  :long "@({
  Examples:
  (assign x (expt 2 10))
  (assign a (aset1 'ascii-map-array (@ a) 66 'Upper-case-B))

  General Form:
  (assign symbol term)
 })

 <p>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 @(tsee
 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:</p>

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

 <p>The macro @('f-put-global') is closely related to @(tsee assign):
 @('(assign var val)') macroexpands to @('(f-put-global 'var val state)').</p>

 <p>The macro @(tsee @) gives convenient access to the value of such globals.
 The @(':')@(tsee ubt) operation has no effect on the @('global-table') of
 @(tsee 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.</p>")

(defxdoc assoc
  :parents (alists acl2-built-ins)
  :short "Look up key in association list"
  :long "@({
  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
 })

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

 <p>The @(see guard) for a call of @('assoc') depends on the test.  In all
 cases, the second argument must satisfy @(tsee alistp).  If the test is @(tsee
 eql), then either the first argument must be suitable for @(tsee eql) (see
 @(see eqlablep)) or the second argument must satisfy @(tsee eqlable-alistp).
 If the test is @(tsee eq), then either the first argument must be a symbol or
 the second argument must satisfy @(tsee symbol-alistp).</p>

 <p>See @(see equality-variants) for a discussion of the relation between
 @('assoc') and its variants:</p>

 <blockquote><p>@('(assoc-eq x alist)') is equivalent to @('(assoc x alist
 :test 'eq)');</p>

 <p>@('(assoc-equal x alist)') is equivalent to @('(assoc x alist :test
 'equal)').</p></blockquote>

 <p>In particular, reasoning about any of these primitives reduces to reasoning
 about the function @('assoc-equal').</p>

 <p>@('Assoc') is defined by Common Lisp.  See any Common Lisp documentation
 for more information.</p>

 @(def assoc-equal)")

(defxdoc assoc-keyword
  :parents (keyword-value-listp acl2-built-ins)
  :short "Look up key in a @(tsee keyword-value-listp)"
  :long "<p>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.</p>

 <p>The @(see guard) for @('(assoc-keyword key l)') is @('(keyword-value-listp
 l)').</p>

 @(def assoc-keyword)")

(defxdoc assoc-string-equal
  :parents (alists acl2-built-ins)
  :short "Look up key, a string, in association list"
  :long "<p>@('(Assoc-string-equal x alist)') is similar to @(tsee
 assoc-equal).  However, for string @('x') and alist @('alist'), the comparison
 of @('x') with successive keys in @('alist') is done using @(tsee
 string-equal) rather than @(tsee equal).</p>

 <p>The @(see guard) for @('assoc-string-equal') requires that @('x') is a
 string and @('alist') is an alist.</p>

 @(def assoc-string-equal)")

(defxdoc assume-true-false-aggressive-p
  :parents (rewrite system-attachments)
  :short "Control rewriter's use of the @(see type-alist) with @('IF') calls"
  :long "<p>This topic concerns an advanced control for the ACL2 prover.</p>

 <p>This zero-ary attachable system function controls the rewriter's use of the
 @(see type-alist) when diving into calls of @('IF').  By default, when ACL2
 rewrites what amounts to @('(if (or test1 test2) (if test1 _ x) _)'), the
 type-alist will fail to note that @('test2') is true when rewriting @('x').
 Attach the function @('constant-t-function-arity-0') to strengthen the use of
 the type-alist so that @('test2') is instead noted as true in that case.  Note
 that this strengthening may slow down ACL2 considerably in some cases, and
 should rarely if ever be necessary when calling the prover; but it can be
 useful in applications that call the rewriter directly.  Attach the function
 @('constant-nil-function-arity-0') to restore the default behavior.</p>")

(defxdoc atom
  :parents (conses acl2-built-ins)
  :short "Recognizer for atoms"
  :long "<p>@('(atom x)') is true if and only if @('x') is an atom, i.e., not a
 @(tsee cons) pair.</p>

 <p>@('Atom') has a @(see guard) of @('t'), and is a Common Lisp function.  See
 any Common Lisp documentation for more information.</p>

 @(def atom)")

(defxdoc atom-listp
  :parents (atom lists acl2-built-ins)
  :short "Recognizer for a true list of @(see atom)s"
  :long "<p>The predicate @('atom-listp') tests whether its argument is a
 @(tsee true-listp) of @(see atom)s, i.e., of non-conses.</p>

 @(def atom-listp)")

(defxdoc attach-stobj
  :parents (defabsstobj)
  :short "Attach an “implementation @(see stobj)” to an attachable
 stobj"
  :long "<p>For an illustration of @('attach-stobj'), see @(see
 community-books) directory @('books/demos/attach-stobj/'), in particular file
 @('README.txt') in that directory.  An overview of the subject of this topic
 may be found in the paper, <a
 href='https://cgi.cse.unsw.edu.au/~eptcs/paper.cgi?ACL2in2025.7'>&ldquo;Extended
 Abstract: Mutable Objects with Several Implementations&rdquo;</a> by Matt
 Kaufmann, Yahya Sohail, and Warren A. Hunt Jr.</p>

 <p>This topic assumes familiarity with abstract @(see stobj)s; see @(see
 defabsstobj).  It documents a way to modify the foundation and primitives of
 an abstract @(see stobj), @('gen'), that is introduced by @('defabsstobj')
 using the keyword argument @(':attachable t').  Such a stobj is called an
 <i>attachable</i> stobj.  Execution of its primitives can be provided by
 corresponding primitives of a specified abstract stobj, @('impl'), which we
 say is <i>attached to</i> @('gen') (or: @('impl') is the <i>implementation
 stobj attached to</i> @('gen')); said differently, @('gen') has @('impl') as
 an attachment.  That relationship is specified by the following</p>

 @({
 General Form:
 (attach-stobj gen impl)
 })

 <p>where @('gen') and @('impl') are symbols, @('gen') is not currently the
 @(see name) of any @(see event) (function, macro, constant, stobj, etc.), and
 @('impl') is an abstract stobj.  A subsequent attempt to introduce @('gen') as
 an attachable stobj will require @('gen') and @('impl') to have
 <i>corresponding logical skeletons</i> as described below.  In that case, the
 foundation of @('gen'), as well as execution of the primitives of @('gen'),
 will effectively be provided by @('impl'); details are below.</p>

 <p>In the General Form above, @('impl') is allowed to be @('nil'), i.e., the
 event @('(attach-stobj gen nil)') is legal, where it is still required that
 @('gen') not be the name of any existing event.  The effect of this
 ``attachment'' of @('nil') is to cancel the effect of any previous
 @('(attach-stobj gen impl)') on any future introduction of @('gen').  Below,
 we assume the common case that @('impl') is not @('nil').</p>

 <p>Note that @('impl') may itself have an attachment, say, @('impl2'), in
 which case we say that @('impl2') is attached to @('gen').  If furthermore
 @('impl3') is attached to @('impl2'), then @('impl3') is said to be attached
 to @('gen'); and so on.</p>

 <p>The guiding principle is that @('gen') is modified by its attachment to
 @('impl') so that @('gen') behaves exactly as @('impl') except for the names
 introduced and the @(':non-executable') keyword.  Specifically, if @('impl')
 is attached to @('gen'), then the following properties hold.  (See @(see
 defabsstobj) for the notion of a &ldquo;function spec&rdquo; and its
 &ldquo;completion&rdquo;.)</p>

 <ul>

 <li>Both @('gen') and @('impl') are abstract stobjs, and moreover, @('gen') is
 an attachable stobj.</li>

 <li>@('Impl') was introduced before the use of @('attach-stobj') to attach
 @('impl') to @('gen'), which took place before @('gen') was introduced.</li>

 <li>@('Gen') and @('impl') have corresponding logical skeletons (as defined
 below).  In particular, each primitive of @('gen') has the same logical
 meaning (i.e., the same @(':logic') function) as the corresponding primitive
 of @('impl').</li>

 <li>For each primitive @('p_gen') of @('gen') and corresponding primitive
 @('p_impl') of @('impl'), if @('(p_impl . kwd-alist)') is the completion of
 the corresponding function spec for @('p_impl'), then the function spec for
 @('p_gen') is effectively given as @('(p_gen . kwd-alist)'), with the
 following exception.  Each @(':updater') keyword is replaced appropriately, as
 follows: if @('kwd-alist') specifies @(':updater u_impl') and primitive
 @('u_gen') of @('gen') corresponds to primitive @('u_impl') of @('impl'), then
 @(':updater u_impl') is replaced by @(':updater u_gen') to obtain the
 effective function spec for @('p_gen').</li>

 <li>The @(':protect-default') and @(':congruent-to') keyword arguments for
 @('gen') are effectively those of @('impl').</li>

 <li>The @(':non-executable') keyword argument for @('gen') is unchanged by the
 attachment.</li>

 </ul>

 <p>As promised above, we now define when two @('defabsstobj') events have
 <i>corresponding logical skeletons</i>, as follows.  The @(':exports') keyword
 argument of each must be of the same length, establishing a positional one-one
 correspondence between them.  Corresponding exports (i.e., exports in the same
 position) must have the same @(':logic') functions and, if one of them
 specifies @(':updater u1'), then the other must specify @(':updater u2') where
 @('u1') and @('u2') correspond.</p>

 <p>Remarks on Performance.  Stobj attachments are designed to be efficient.
 There is no indirection: in raw Lisp, each primitive macroexpands to a call of
 the @(':exec') primitive of the attachment (which is itself a macro call).
 The trade-off is that when a function @('F') is defined in the course of
 evaluating an @(tsee include-book) event, then if the guard or body of @('F')
 calls an attachable stobj primitive &mdash; either directly or by way of
 inline functions or macroexpansion, and whether or not that stobj has an
 attachment &mdash; then @('F') will be compiled at that time.  (This is in
 contrast to the usual case, where compiled code from the book's compiled file
 will be installed to avoid such recompilation.)  Most likely this will not be
 a noticeable problem in practice, but if it is, then one can define a wrapper
 &mdash; a function that does nothing more than call the primitive &mdash; to
 avoid such recompilation at the cost of a runtime function call for each such
 primitive.  End of Remarks on Performance.</p>

 <p>Note that the notion of redundancy for @('defabsstobj') was not changed by
 support for the @(':attachable') keyword.  As noted in the topic @(see
 redundant-events), a @('defabsstobj') event is redundant if there is already
 an identical such event in the logical @(see world).</p>

 <p>The @(see community-books) directory @('system/tests/attachable-stobjs/')
 has examples that use attachable stobjs.</p>")

(defxdoc |About Models|
  :parents (|Pages Written Especially for the Tours|)
  :short "About Models"
  :long "<p><see topic='@(url |Models of Computer Hardware and Software|)'><img
 src='res/tours/flying.gif'></img></see></p>

 <p>ACL2 is used to construct mathematical models of computer hardware and
 software (i.e., ``digital systems'').</p>

 <p><img src='res/tours/computing-machine.gif'></img></p>

 <p>A <b>mathematical model</b> is a set of mathematical formulas used to
 predict the behavior of some artifact.</p>

 <p>The use of mathematical models allows <b>faster</b> and <b>cheaper</b>
 delivery of <b>better</b> systems.</p>

 <p>Models need not be <b>complete</b> or <b>perfectly accurate</b> to be
 useful to the trained engineer.</p>

 <p>Click <see topic='@(url |Models in Engineering|)'>here</see> for more
 discussion of these assertions in an engineering context.</p>

 <p><see topic='@(url |Models of Computer Hardware and Software|)'><img
 src='res/tours/flying.gif'></img></see></p>")

(defxdoc |About Types|
  :parents (|Pages Written Especially for the Tours|)
  :short "About Types"
  :long "<p>The universe of ACL2 objects includes objects of many different
 types.  For example, @('t') is a ``symbol'' and 3 is an ``integer.''  Roughly
 speaking the objects of ACL2 can be partitioned into the following types:</p>

 <ul>

 <li><see topic='@(url |Numbers in ACL2|)'>Numbers</see> such as @('3, -22/7,
 #c(3 5/2)').</li>

 <li><see topic='@(url |ACL2 Characters|)'>Characters</see> such as @('#\A,
 #\a, #\Space').</li>

 <li><see topic='@(url |ACL2 Strings|)'>Strings</see> such as @('"This is a
 string."').</li>

 <li><see topic='@(url |ACL2 Symbols|)'>Symbols</see> such as @(''abc,
 'smith::abc').</li>

 <li><see topic='@(url |ACL2 Conses or Ordered Pairs|)'>Conses (or
 Ordered Pairs)</see> such as @(''((a . 1) (b . 2))').</li>

 </ul>

 <p>When proving theorems it is important to know the types of object returned
 by a term.  ACL2 uses a complicated heuristic algorithm, called @(tsee
 type-set) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>, to determine what types of objects a term may
 produce.  The user can more or less program the @('type-set') algorithm by
 proving @(tsee type-prescription) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>
 rules.</p>

 <p>ACL2 is an ``untyped'' logic in the sense that the syntax is not typed: It
 is legal to apply a function symbol of n arguments to any n terms, regardless
 of the types of the argument terms.  Thus, it is permitted to write such odd
 expressions as @('(+ t 3)') which sums the symbol @('t') and the integer 3.
 Common Lisp does not prohibit such expressions.  We like untyped languages
 because they are simple to describe, though proving theorems about them can be
 awkward because, unless one is careful in the way one defines or states
 things, unusual cases (like @('(+ t 3)')) can arise.</p>

 <p>To make theorem proving easier in ACL2, the axioms actually define a value
 for such terms.  The value of @('(+ t 3)') is 3; under the ACL2 axioms,
 non-numeric arguments to @('+') are treated as though they were 0.</p>

 <p>You might immediately wonder about our claim that ACL2 is Common Lisp,
 since @('(+ t 3)') is ``an error'' (and will sometimes even ``signal an
 error'') in Common Lisp.  It is to handle this problem that ACL2 has
 <b>guards</b>.  We will discuss guards later in the Walking Tour.  However,
 many new users simply ignore the issue of guards entirely and that is what we
 recommend for now.</p>

 <p>You should now return to <see topic='@(url
 |Revisiting the Admission of App|)'>the Walking Tour</see>.</p>")

(defxdoc |About the ACL2 Home Page|
  :parents (|Pages Written Especially for the Tours|)
  :short "About the ACL2 Home Page"
  :long "<p><see topic='@(url |What Is ACL2(Q)|)'><img
 src='res/tours/flying.gif'></img></see></p>

 <p>The <a href='https://www.cs.utexas.edu/users/moore/acl2/'>ACL2 Home Page</a>
 on the web contains links to demos, publications, mailing lists, installation
 instructions, and more &mdash; and, especially, to the
 @(`(:raw (combined-manual-ref))`), which provides online documentation for
 ACL2 and its libraries, known as ``books''.</p>

 <p>For example, to use the online documentation to find out about @(see
 rewrite) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> rules you could click on the link.  (If
 you do that, remember to use your browser's <b>Back Button</b> to come back
 here.)</p>

 <p>The tiny warning signs <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> mark links that lead out of the introductory-level
 material and into the user documentation.  We advise against following such
 links upon your first reading of the documentation.</p>

 <p>At the end of the tours you will have a chance to revisit them quickly to
 explore alternative paths more fully.</p>

 <p><see topic='@(url |What Is ACL2(Q)|)'><img
 src='res/tours/flying.gif'></img></see></p>")

(defxdoc |About the Admission of Recursive Definitions|
  :parents (|Pages Written Especially for the Tours|)
  :short "About the Admission of Recursive Definitions"
  :long "<p>You can't just add any formula as an axiom or definition and expect
 the logic to stay sound!  For example, if we were permitted to define @('(APP
 X Y)') so that it was equal to @('(NOT (APP X Y))') then we could prove
 anything.  The purported ``definition'' of @('APP') must have several
 properties to be admitted to the logic as a new axiom.</p>

 <p>The key property a recursive definition must have is that the recursion
 terminate.  This, along with some syntactic criteria, ensures us that there
 exists a function satisfying the definition.</p>

 <p>Termination must be proved before the definition is admitted.  This is done
 in general by finding a measure of the arguments of the function and a
 well-founded relation such that the arguments ``get smaller'' every time a
 recursive branch is taken.</p>

 <p>For @('app') the measure is the ``size'' of the first argument, @('x'), as
 determined by the primitive function @(tsee acl2-count) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>.
 The well-founded relation used in this example is @(tsee o-p) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>,
 which is the standard ordering on the ordinals less than ``epsilon naught.''
 These particular choices for @('app') were made ``automatically'' by ACL2.
 But they are in fact determined by various ``default'' settings.  The user of
 ACL2 can change the defaults or specify a ``hint'' to the @(tsee defun) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>
 command to specify the measure and relation.</p>

 <p>You should now return to <see topic='@(url
 |Revisiting the Admission of App|)'>the Walking Tour</see>.</p>")

(defxdoc |About the Prompt|
  :parents (|Pages Written Especially for the Tours|)
  :short "About the Prompt"
  :long "<p>The string ``@('ACL2 !>')'' is the ACL2 prompt.</p>

 <p>The prompt tells the user that an ACL2 @(see command) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> is expected.  In addition, the prompt
 tells us a little about the current state of the ACL2 command interpreter.  We
 explain the prompt briefly below.  But first we talk about the command
 interpreter.</p>

 <p>An ACL2 command is generally a Lisp expression to be evaluated.  There are
 some unusual commands (such as @(':')@(see q) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see> for
 <b>quitting</b> ACL2) which cause other behavior.  But most commands are read,
 evaluated, and then have their results printed.  Thus, we call the command
 interpreter a ``read-eval-print loop.''  The ACL2 command interpreter is named
 @(tsee LD) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> (after Lisp's ``load'').</p>

 <p>When a command is read, all the symbols in it are converted to uppercase.
 Thus, typing @('(defun app ...)') is the same as typing @('(DEFUN APP ...)')
 or @('(defun App ...)').  There are ways to force lowercase case characters
 into symbols but we won't discuss them here.  A consequence of Common Lisp's
 default uppercasing is that you'll see a general lack of concern over the case
 used when symbols are displayed in this documentation.</p>

 <p>In addition, symbols ``belong'' to ``packages'' which give the user a way
 to control namespaces.  The prompt tells us which package is the default one,
 namely @('"ACL2"').  That means when we call @('car'), for example, we are
 invoking the standard definition of that symbol.  If the packager were
 @('"JONES"') then @('car') would refer to the definition of that symbol in
 that package (which may or may not be different depending on what symbols were
 imported into that package.</p>

 <p>A command like <b>(defun app (x y) ...)</b> causes ACL2 to evaluate the
 @(see defun) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> function on <b>app</b>, <b>(x y)</b> and
 <b>...</b>.  When that command is evaluated it prints some information to the
 terminal explaining the processing of the proposed definition.  It returns the
 symbol @('APP') as its value, which is printed by the command interpreter.
 (Actually, @('defun') is not a function but a <see topic='@(url
 DEFMACRO)'>macro</see> <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> which expands to a form that involves @(tsee state)
 <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>, a necessary precondition to printing output to the
 terminal and to ``changing'' the set of axioms.  But we do not discuss this
 further here.)</p>

 <p>The @('defun') command is an example of a special kind of command called an
 ``event.''  @(see Events) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> are those commands that change the ``logical
 world'' by adding such things as axioms or theorems to ACL2's database.  See
 @(see world) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>.  But not every command is an event command.</p>

 <p>A command like <b>(app '(1 2 3) '(4 5 6 7))</b> is an example of a
 non-event.  It is processed the same general way: the function <b>app</b> is
 applied to the indicated arguments and the result is printed.  The function
 <b>app</b> does not print anything and does not change the ``world.''</p>

 <p>A third kind of command is one that displays information about the current
 logical world or that ``roll back'' to previous versions of the world.  Such
 commands are called ``@(see history)'' <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>
 commands.</p>

 <p>What does the ACL2 prompt tell us about the read-eval-print loop?  The
 prompt ``@('ACL2 !>')'' tells us that the command will be read with @(tsee
 current-package) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> set to @('"ACL2"'), that guard checking (see
 @(see set-guard-checking) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>) is on (``@('!')''), and that we are at the
 top-level (there is only one ``@('>')'').  For more about the prompt, see
 @(see default-print-prompt) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>.</p>

 <p>You should now return to <see topic='@(url
 |Revisiting the Admission of App|)'>the Walking Tour</see>.</p>")

(defxdoc |An Example Common Lisp Function Definition|
  :parents (|Pages Written Especially for the Tours|)
  :short "An Example Common Lisp Function Definition"
  :long "<p><see topic='@(url |An Example of ACL2 in Use|)'><img
 src='res/tours/walking.gif'></img></see></p>

 <p>Consider the binary trees @('x') and @('y') below.</p>

 <p><img src='res/tours/binary-trees-x-y.gif'></img></p>

 <p>In Lisp, @('x') is written as the list @(''(A B)') or, equivalently, as
 @(''(A B . NIL)').  Similarly, @('y') may be written @(''(C D E)').  Suppose
 we wish to replace the right-most tip of @('x') by the entire tree @('y').
 This is denoted @('(app x y)'), where @('app') stands for ``append''.</p>

 <p><img src='res/tours/binary-trees-app.gif'></img></p>

 <p>We can define @('app') with:</p>

 <code>
 <b>(defun app (x y)</b>                           <i>; Concatenate x and y.</i>
   <b>(declare (type (satisfies true-listp) x))</b><i>; We expect x to end in NIL.</i>
   <b>(cond ((endp x) y)</b>                       <i>; If x is empty, return y.</i>
         <b>(t (cons (car x)</b>                   <i>; Else, copy first node</i>
                  <b>(app (cdr x) y)))))</b>       <i>;  and recur into next.</i>
 </code>

 <p>If you defined this function in some Common Lisp, then to run @('app') on
 the @('x') and @('y') above you could then type</p>

 @({
  (app '(A B) '(C D E))
 })

 <p>and Common Lisp will print the result @('(A B C D E)').</p>

 <p><see topic='@(url |An Example of ACL2 in Use|)'><img
 src='res/tours/walking.gif'></img></see></p>")

(defxdoc |An Example of ACL2 in Use|
  :parents (|Pages Written Especially for the Tours|)
  :short "An Example of ACL2 in Use"
  :long "<p><see topic='@(url |How To Find Out about ACL2 Functions|)'><img
 src='res/tours/walking.gif'></img></see></p>

 <p>To introduce you to ACL2 we will consider the @('app') function discussed
 in the <see topic='@(url |Common Lisp|)'>Common Lisp</see> page, <b>except</b>
 we will omit for the moment the <b>declare</b> form, which in ACL2 is called a
 <b>guard</b>.</p>

 <p>Guards are arbitrary ACL2 terms that express the ``intended domain'' of
 functions.  In that sense, guards are akin to type signatures.  However,
 Common Lisp and ACL2 are untyped programming languages: while the language
 supports several different data types and the types of objects can be
 determined by predicates at runtime, any type of object may be passed to any
 function.  Thus, guards are ``extra-logical.''  Recognizing both the practical
 and intellectual value of knowing that your functions are applied to the kinds
 of objects you intend, ACL2 imposes guards on Common Lisp and provides a means
 of proving that functions are used as intended.  But the story is necessarily
 complicated and we do not recommend it to the new user.  Get used to the fact
 that any ACL2 function may be applied to any objects and program accordingly.
 Read about guards later.</p>

 <p>Here is the definition again</p>

 <code>
 <b>(defun app (x y)</b>
   <b>(cond ((endp x) y)</b>
         <b>(t (cons (car x) </b>
                  <b>(app (cdr x) y)))))</b>
 </code>

 <p>The next few stops along the Walking Tour will show you</p>

 <ul>

 <li>how to use the ACL2 documentation,</li>

 <li>what happens when the above definition is submitted to ACL2,</li>

 <li>what happens when you evaluate calls of @('app'),</li>

 <li>what one simple theorem about @('app') looks like,</li>

 <li>how ACL2 proves the theorem, and</li>

 <li>how that theorem can be used in another proof.</li>

 </ul>

 <p>Along the way we will talk about the <b>definitional principle</b>,
 <b>types</b>, the ACL2 <b>read-eval-print loop</b>, and how the <b>theorem
 prover</b> works.</p>

 <p>When we complete this part of the tour we will return briefly to the notion
 of <b>guards</b> and revisit several of the topics above in that context.</p>

 <p><see topic='@(url |How To Find Out about ACL2 Functions|)'><img
 src='res/tours/walking.gif'></img></see></p>")

(defxdoc |Analyzing Common Lisp Models|
  :parents (|Pages Written Especially for the Tours|)
  :short "Analyzing Common Lisp Models"
  :long "<p>To analyze a model you must be able to reason about the operations
 and relations involved.  Perhaps, for example, some aspect of the model
 depends upon the fact that the concatenation operation is associative.</p>

 <p>In any Common Lisp you can confirm that</p>

 @({
  (app '(A B) (app '(C D) '(E F)))
 })

 <p>and</p>

 @({
  (app (app '(A B) '(C D)) '(E F)))
 })

 <p>both evaluate to the same thing, @('(A B C D E F)').</p>

 <p>But what distinguishes ACL2 (the logic) from applicative Common Lisp (the
 language) is that in ACL2 you can <b>prove</b> that the concatenation function
 @('app') is associative when its arguments are true-lists, whereas in Common
 Lisp all you can do is test that proposition.</p>

 <p>That is, in ACL2 it makes sense to say that the following formula is a
 ``theorem.''</p>

 <code>
 <b>Theorem</b> Associativity of App
 (implies (and (true-listp a)
               (true-listp b))
          (equal (app (app a b) c)
                 (app a (app b c))))
 </code>

 <p>Theorems about the properties of models are proved by symbolically
 manipulating the operations and relations involved.  If the concatenation of
 sequences is involved in your model, then you may well need the theorem above
 in order to that your model has some particular property.</p>")

(defxdoc backchaining
  :parents (rule-classes)
  :short "Attempting to relieve the hypotheses of a rule"
  :long "<p>When the theorem prover attempts to apply a rule (e.g., a @(see
  rewrite) rule), it must relieve (prove) the hypotheses of that rule.  In the
  ACL2 community, this process of relieving hypotheses is called
  backchaining.</p>

  <p>There is no such thing as a backchaining or backward-chaining rule
  class (see @(see rule-classes)) in ACL2.</p>")

(defxdoc backchain-limit
  :parents (rewrite meta linear type-prescription)
  :short "Limiting the effort expended on relieving hypotheses"
  :long "<p>Before ACL2 can apply a rule with hypotheses, it must establish
 that the hypotheses are true.  (We ignore the relaxing of this requirement
 afforded by @(tsee case-split)s and @(tsee force)d hypotheses.)  ACL2
 typically establishes each hypothesis by backchaining &mdash; instantiating
 the hypothesis and then rewriting it recursively.  Here we describe how ACL2
 allows the user to limit backchaining.  At the end, below, we describe the
 function @(tsee backchain-limit).</p>

 <p>Each hypothesis of a @(tsee rewrite), @(tsee meta), @(tsee linear), or
 @(tsee type-prescription) rule is assigned a backchain-limit when the rule is
 stored.  By default, this limit is @('nil'), denoting infinity (no limit).
 However, the value used for the default may be set to a non-negative integer
 (or to @('nil')) by the user; see @(see set-default-backchain-limit).  The
 default is overridden when a @(':backchain-limit-lst') is supplied explicitly
 with the rule; see @(see rule-classes).  The number of recursive applications
 of backchaining starting with the hypothesis of a rule is limited to the
 backchain-limit associated with that hypothesis.</p>

 <p>Moreover, the user may set global backchain-limits that limit the total
 backchaining depth.  See @(see set-backchain-limit).  One limit is for the use
 of @(tsee rewrite), @(tsee meta), and @(tsee linear) rules, while the other
 limit is for so-called ``type reasoning'', which uses rules of class @(tsee
 type-prescription) rules (see @(see type-reasoning)).  The two limits operate
 independently.  Below, we discuss the first kind of backchain limits, i.e.,
 for other than @(tsee type-prescription) rules, except as otherwise indicated;
 but the mechanism for those rules is similar.</p>

 <p>Below we lay out the precise sense in which a global backchain-limit
 interacts with the backchain-limits of individual rules in order to limit
 backchaining.  But first we note that when further backchaining is disallowed,
 ACL2 can still prove a hypothesis in a given context by using that contextual
 information.  In fact, type reasoning may be used (except that a weaker
 version of it is used in the second case above, i.e., where we are already
 doing type-set reasoning).  Thus, the relieving of hypotheses may be limited
 to the use of contextual information (without backchaining, i.e., without
 recursively rewriting hypotheses) by executing @(':set-backchain-limit
 0').</p>

 <p>Recall that there are two sorts of backchain limits: those applied to
 hypotheses of individual rules, as assigned by their @(':')@(tsee
 rule-classes) or else taken from the default (see @(see
 set-default-backchain-limit)); and the global limit, initially @('nil') (no
 limit) but settable with @(':')@(tsee set-backchain-limit).  Here is how these
 two types of limits interact to limit backchaining, i.e., recursive rewriting
 of hypotheses.  ACL2 maintains a current backchain limit, which is the limit
 on the depth of recursive calls to the rewriter, as well as a current
 backchain depth, which is initially 0 and is incremented each time ACL2
 backchains (and is decremented when a backchain completes).  When ACL2 begins
 to rewrite a literal (crudely, one of the ``top-level'' terms of the goal
 currently being worked on), it sets the current backchain-limit to the global
 value, which is initially @('nil') but can be set using @(':')@(tsee
 set-backchain-limit).  When ACL2 is preparing to relieve a hypothesis by
 backchaining (hence, after it has already tried type-set reasoning), it first
 makes sure that the current backchain limit is greater than the current
 backchain depth.  If not, then it refuses to relieve that hypothesis.
 Otherwise, it increments the current backchain depth and calculates a new
 current backchain-limit by taking the minimum of two values: the existing
 current backchain-limit, and the sum of the current backchain depth and the
 backchain-limit associated with the hypothesis.  Thus, ACL2 only modifies the
 current backchain-limit if it is necessary to decrease that limit in order to
 respect the backchain limit associated with the hypothesis.</p>

 <p>We illustrate with the following examples.</p>

 @({
  ; We stub out some functions so that we can reason about them.

  (defstub p0 (x) t)
  (defstub p1 (x) t)
  (defstub p2 (x) t)
  (defstub p3 (x) t)

  ; Initially, the default-backchain-limit is nil, or infinite.

  (defaxiom p2-implies-p1-limitless
    (implies (p2 x)
             (p1 x)))

  ; The following rule will have a backchain-limit of 0.

  (defaxiom p1-implies-p0-limit-0
    (implies (p1 x)
             (p0 x))
    :rule-classes ((:rewrite :backchain-limit-lst 0)))

  ; We have (p2 x) ==> (p1 x) ==> (p0 x).  We wish to establish that
  ; (p2 x) ==> (p0 x).  Normally, this would be no problem, but here
  ; we fail because ACL2 cannot establish (p0 x) by type-set reasoning
  ; alone.

  (thm
    (implies (p2 x)
             (p0 x)))

  ; We set the default-backchain-limit (for rewriting) to 1.

  :set-default-backchain-limit 1

  ; The following is more powerful than p1-implies-p0-limit-0
  ; because it can use rewrite rules to establish (p1 x).

  (defaxiom p1-implies-p0-limit-1
    (implies (p1 x)
             (p0 x)))

  ; This theorem will succeed:

  (thm
    (implies (p2 x)
             (p0 x)))

  ; We return the default-backchain-limit to its initial value.

  :set-default-backchain-limit nil

  ; Here is our last axiom.

  (defaxiom p3-implies-p2-limitless
    (implies (p3 x)
             (p2 x)))

  ; We now have (p3 x) ==> (p2 x) ==> (p1 x) ==> (p0 x).  However the
  ; rule p1-implies-p0-limit-1 has a backchain-limit of 1; hence we
  ; are not allowed to backchain far enough back to use
  ; p3-implies-p2-limitless.  We therefore lose.

  (defthm will-fail
    (implies (p3 x)
             (p0 x)))
 })

 <p>Finally, we remark that to see the current global backchain-limits, issue
 the following commands.</p>

 @({
  (backchain-limit wrld :ts) ; backchain limit for type-set reasoning
  (backchain-limit wrld :rewrite) ; backchain limit for rewriting
 })")

(defxdoc backquote
  :parents (reader)
  :short "Variant of quotation introducing templates for data structures"
  :long "<p>ACL2 supports the backquote (@('`')) construct of Common Lisp.  See
 any Common Lisp documentation for details, for example, its <a
 href='https://www.lispworks.com/documentation/HyperSpec/Body/02_df.htm'>discussion
 in the Common Lisp HyperSpec</a>.  Here we give only a brief introduction.</p>

 <p>Together with the use of comma (@(',')) and comma-atsign (@(',@')),
 backquote provides a variant of quote that supports an escape mechanism, as
 illustrated by the following examples.</p>

 @({
 ACL2 !>`(a b c)
 (A B C)
 ACL2 !>(let ((x '(a b c))) `(1 ,(cdr x) 2))
 (1 (B C) 2)
 ACL2 !>(let ((x '(a b c))) `(1 ,@(cdr x) 2))
 (1 B C 2)
 ACL2 !>
 })

 <p>The first example above illustrates that backquote is much like quote.  The
 second example shows how a comma escapes from the quotation, inserting the
 value of the object that follows the comma.  The third example is similar to
 the second, except that it uses comma followed by an atsign, which splices in
 the value (which must satisfy @(tsee true-listp)) rather than inserting
 it.</p>")

(defxdoc badge
  :parents (apply$)
  :short "Syntactic requirements on a function symbol to be used by @('apply$')"
  :long "<p>``Badge'' is both the name of an ACL2 function and the name of a
  concept key to the @(tsee apply$) machinery.  We discuss the function named
  @('badge') first.  The discussion also mentions the concept of warrants,
  which are easily confused with badges.  See the discussion of <b>Badges
  versus Warrants</b> at the top of @('defbadge').  But roughly put, badges
  extend the ACL2 syntax and warrants extend the proof theory.  You'll need a
  badge for @('fn') to allow the system to syntactically analyze @('(apply$ 'fn
  ...)').  You'll need a both a badge and a warrant for @('fn') if you wish to
  reason about that term with ACL2.</p>

  <p>General Form:</p>
  @({(badge fn)})

  <p>The argument, @('fn'), is expected to be a function symbol.  If @('fn') is
  one of about 800 ACL2 primitives (discussed below) or is a user-defined
  function successfully processed by either the event @(tsee defbadge) or the
  event @(tsee defwarrant), the result is an object, called the ``badge'' of
  @('fn'), which among other things specifies the @(see ilk) of each formal of
  @('fn').  Otherwise, an error is caused.  We explain below, where we define
  the concepts of the ``out arity,'' ``ilks,'' and ``tameness requirements'' of
  @('fn')'s badge.</p>

  <p>A function symbol must have a badge in order to @('apply$') the symbol and
  it is up to you, the user, to invoke an event that will assign a badge to
  your user-defined functions, if possible.  @('Defbadge') will assign a badge
  to a function symbol, if possible, and @('defwarrant') will assign both a
  badge (if the function symbol doesn't already have one) and a @(tsee
  warrant), if possible.  The macro @(tsee defun$) is just an abbreviation for
  a @('defun') followed by a @('defwarrant').  Almost all primitive system
  functions already have badges.</p>

  <p>The complete list of badged primitives can be seen by evaluating</p>

  @({
  (append '(BADGE TAMEP TAMEP-FUNCTIONP SUITABLY-TAMEP-LISTP
                  APPLY$ EV$)
          (strip-cars *badge-prim-falist*))
  })

  <p>@('Badge') is a defined function in ACL2.  You can inspect its definition
  with</p>

  @({ACL2 !>:pe badge
  })

  <p>and see that after handling the built-in symbols it defers to the
  undefined function @(tsee badge-userfn).  In the evaluation theory,
  @('badge-userfn') has an attachment that returns the badge computed by
  @('defbadge') or @('defwarrant').  But in the proof theory, @('badge-userfn')
  is undefined and the @(tsee warrant) for @('fn') specifies the badge of
  @('fn').  Thus, in the proof theory, you cannot reason about the application
  of a non-primitive function unless there is a warrant for the function
  available as a hypothesis.</p>

  <p>The rest of this documentation illustrates and explains what badges mean,
  starting with a few examples.</p>

  @({
  ACL2 !>(badge 'cons)
  (APPLY$-BADGE 2 1 . T)

  ACL2 !>(badge 'apply$)
  (APPLY$-BADGE 2 1 :FN NIL)

  ACL2 !>(badge 'foldr)
  (APPLY$-BADGE 3 1 NIL :FN NIL)
  })

  <p>The last example assumes that @('foldr') has been defined with</p>

  @({
  (defun$ foldr (lst fn init)
    (if (endp lst)
        init
        (apply$ fn
                (list (car lst)
                      (foldr (cdr lst) fn init)))))
  })

  <p>In general, badges have the form @('(APPLY$-BADGE n k . ilks)'), where
  @('n') is the arity of @('fn'), @('k') is the out arity (i.e., the number of
  results returned by @('fn')) and @('ilks') is either @('T') or a list of
  @('n') tokens.  Each token is either @(':FN'), @(':EXPR'), or @('NIL').</p>

  <p>The badge of @('fn'), if any, is computed when the event @('(defbadge
  fn)') or @('(defwarrant fn)') completes successfully.  See @(tsee defbadge)
  for a sketch of the algorithm used to compute badges.  Here though we are
  just concerned with how badges impact @('apply$').</p>

  <p>The @('ilks') of a function, @('fn'), determines the ``tameness
  requirements'' mentioned in the specification of @(tsee apply$).  When the
  @('ilks') component of @('fn')'s badge is a list, it has as many elements as
  there are formals to @('fn') and each successive element is called the
  <i>ilk</i> of the corresponding formal.  For example, given the definition of
  @('foldr') above and the badge shown for it, the first and third formals,
  @('lst') and @('init'), each have ilk @('NIL') and the second formal,
  @('fn'), has ilk @(':FN').  In the special case that @('ilks') is not a list
  it is @('T') and we just say each formal has <i>ilk</i> @('NIL') -- treating
  that @('T') as a suitably long list of @('NIL')s.</p>

  <p>Each non-@('NIL') ilk imposes a <i>tameness requirement</i> on @('(apply$
  fn args)').  If a formal has ilk @(':FN') the corresponding element of
  @('args') must satisfy @('tamep-functionp').  If a formal has ilk @(':EXPR')
  the corresponding element of @('args') must satisfy @('tamep').  Ilk @('NIL')
  imposes no requirement.  (Thus, if the @('ilks') of @('fn')'s badge is
  @('T'), as it is for @('cons') for example, there is no tameness requirement
  at all.)  See @(see tame) for a discussion of the various notions of
  tameness.</p>

  <p>Informally, if a formal's ilk is @(':FN'), the corresponding element of
  @('args') must be a tame function symbol or well-formed @('LAMBDA') object.
  If a formal's ilk is @(':EXPR'), the corresponding element of @('args') must
  be a tame expression.</p>

  <p>If a formal has ilk @(':FN') then you are allowed to put a @(tsee lambda$)
  expression in that slot.  Any quoted @('LAMBDA') object you explicitly write
  in such a slot must be well-formed (see @(see well-formed-lambda-objectp)).
  Well-formedness can be hard to achieve in quoted hand-written @('LAMBDA')
  objects; we recommend that you use @('lambda$')!  But the restrictions on
  what can occupy a @(':FN') slot are enforced when user input is translated
  into formal terms.  It is possible to circumvent these syntactic checks
  without endangering soundness: axiomatically @('apply$') puts no restrictions
  on its arguments, it just doesn't behave the way you might expect on
  ill-formed @('LAMBDA') objects.  See @(see
  gratuitous-lambda-object-restrictions).</p>

  <p><b>Clarification</b>: The careful reader will note that the formal
  requirement on a @(':FN') argument is that it must satisfy
  @('tamep-functionp').  Inspection of the definition of @('tamep-functionp')
  reveals that the argument must either be badged symbol with ilks @('T') or
  else be a tame @('LAMBDA') object.  But in the informal description above we
  said that it must be a ``tame function symbol or a <i>well-formed</i>
  @('LAMBDA') object.''  Well-formedness implies tameness but they are not the
  same.  What's going on?  The reason for this and related discrepancies in the
  documentation is that there is a tension between the logical definition of
  @('apply$') and the practical business of executing it.  The former involves
  the existence of a model, soundness, and the difficulty of proving theorems
  about @('apply$').  The latter involves the Common Lisp compiler.  We want
  the logical foundations to be simple so we -- and you -- can reason about
  @('apply$'), but the compiler imposes unavoidable and complicated
  restrictions.  The upshot is that the logical foundations assign meaning to
  @('LAMBDA') objects that cannot be compiled.  Applying merely ``tame''
  @('LAMBDA')s is slower than applying ``well-formed'' ones.  In a sense by
  acting like ``tame @('LAMBDA') objects'' and ``well-formed @('LAMBDA')
  objects'' are the same thing we're trying to trick you!  If you ever have
  occasion to formally express the restrictions on @('apply$') in some theorem,
  use @('tamep-functionp').  But when you write concrete @('LAMBDA') constants,
  try to keep them well-formed.  We try to encourage this by providing
  @(tsee lambda$), which guarantees well-formedness at translate-time, and by
  implementing full well-formedness checks -- not just tameness checks -- on
  quoted @('LAMBDA') objects in @(':FN') slots.  And we give you ways to
  circumvent these checks -- see @(see gratuitous-lambda-object-restrictions)
  -- if you really mean to.</p>")

(defxdoc badge-userfn
  :parents (apply$)
  :short "Undefined function used by @('badge') on non-primitives"
  :long "<p>When @(tsee badge) is given a non-primitive function symbol @('fn')
   it calls this function to determine the badge of @('fn').  But this function
   is undefined.  In the proof theory, its value on a given function symbol
   @('fn') is specified, if at all, by the @(tsee warrant) for @('fn') which
   must be available as a hypothesis in the formula being proved.  In the
   evaluation theory, @('badge-userfn') has an attachment that makes it behave
   as though all warrants are assumed.  See @(tsee badge) for details.</p>")

(defxdoc basics
  :parents (programming)
  :short "Basic control structures for @(see programming) like @(see if) and
 @(see cond), binding operators like @(see let) and @(see flet), multiple-value
 constructs like @(see mv), and so forth.")

(defxdoc bdd
  :parents (acl2 boolean-reasoning proof-automation)
  :short "Ordered binary decision diagrams with rewriting"
  :long "<p>Note.  The ACL2 bdd capability has been essentially superseded by
 GL; see @(see gl).</p>

 <p>Ordered binary decision diagrams (OBDDs, often simply called BDDs) are a
 technique, originally published by Randy Bryant, for the efficient
 simplification of Boolean expressions.  In ACL2 we combine this technique with
 rewriting to handle arbitrary ACL2 terms that can represent not only Boolean
 values, but non-Boolean values as well.  In particular, we provide a setting
 for deciding equality of bit vectors (lists of Boolean values).</p>

 <p>An introduction to BDDs for the automated reasoning community may be found
 in ``Introduction to the OBDD Algorithm for the ATP Community'' by J Moore,
 <i>Journal of Automated Reasoning</i> (1994), pp. 33&ndash;45.  (This paper
 also appears as Technical Report #84 from Computational Logic, Inc.)</p>

 <p>Further information about BDDs in ACL2 can be found in the subtopics of
 this @(see documentation) section.  In particular, see @(see bdd-introduction)
 for a good starting place that provides a number of examples.</p>

 <p>See @(see hints) for a description of @(':bdd') hints.  For quick
 reference, here is an example; but only the @(':vars') part of the hint is
 required, as explained in the documentation for @(see hints).  The values
 shown are the defaults.</p>

 @({
  (:vars nil :bdd-constructors (cons) :prove t :literal :all)
 })

 <p>We suggest that you next visit the documentation topic @(see
 BDD-INTRODUCTION).</p>")

(defxdoc bdd-algorithm
  :parents (bdd)
  :short "Summary of the BDD algorithm in ACL2"
  :long "<p>The BDD algorithm in ACL2 uses a combination of manipulation of
 @('IF') terms and unconditional rewriting.  In this discussion we begin with
 some relevant mathematical theory.  This is followed by a description of how
 ACL2 does BDDs, including concluding discussions of soundness, completeness,
 and efficiency.</p>

 <p>We recommend that you read the other documentation about BDDs in ACL2
 before reading the rather technical material that follows.  See @(see
 BDD).</p>

 <p>Here is an outline of our presentation.  Readers who want a user
 perspective, without undue mathematical theory, may wish to skip to Part (B),
 referring to Part (A) only on occasion if necessary.</p>

 <p>(A) <b>Mathematical Considerations</b></p>

 <blockquote>

 <p>(A1) BDD term order</p>

 <p>(A2) BDD-constructors and BDD terms, and their connection with aborting the
 BDD algorithm</p>

 <p>(A3) Canonical BDD terms</p>

 <p>(A4) A theorem stating the equivalence of provable and syntactic equality
 for canonical BDD terms</p>

 </blockquote>

 <p>(B) <b>Algorithmic Considerations</b></p>

 <blockquote>

 <p>(B1) BDD rules (rules used by the rewriting portion of the ACL2 BDD
 algorithm)</p>

 <p>(B2) Terms ``known to be Boolean''</p>

 <p>(B3) An ``IF-lifting'' operation used by the algorithm, as well as an
 iterative version of that operation</p>

 <p>(B4) The ACL2 BDD algorithm</p>

 <p>(B5) Soundness and Completeness of the ACL2 BDD algorithm</p>

 <p>(B6) Efficiency considerations</p></blockquote>

 <p>(A) <b>Mathematical Considerations</b></p>

 <p>(A1) <i>BDD term order</i></p>

 <p>Our BDD algorithm creates a total ``BDD term order'' on ACL2 terms, on the
 fly.  We use this order in our discussions below of IF-lifting and of
 canonical BDD terms, and in the algorithm's use of commutativity.  The
 particular order is unimportant, except that we guarantee (for purposes of
 commutative functions) that constants are smaller in this order than
 non-constants.</p>

 <p>(A2) <i>BDD-constructors</i> (assumed to be @(''(cons)')) and <i>BDD
 terms</i></p>

 <p>We take as given a list of function symbols that we call the
 ``BDD-constructors.''  By default, the only BDD-constructor is @(tsee cons),
 although it is legal to specify any list of function symbols as the
 BDD-constructors, either by using the @(see acl2-defaults-table) (see @(see
 acl2-defaults-table)) or by supplying a @(':BDD-CONSTRUCTORS') hint (see @(see
 hints)).  Warning: this capability is largely untested and may produce
 undesirable results.  Henceforth, except when explicitly stated to the
 contrary, we assume that BDD-constructors is @(''(cons)').</p>

 <p>Roughly speaking, a @(see BDD) term is the sort of @(see term) produced by
 our BDD algorithm, namely a tree with all @(tsee cons) nodes lying above all
 non-@('CONS') nodes.  More formally, a @(see term) is said to be a @(see BDD)
 term if it contains <b>no</b> subterm of either of the following forms, where
 @('f') is not @('CONS').</p>

 @({
  (f ... (CONS ...) ...)

  (f ... 'x ...)  ; where (consp x) = t
 })

 <p>We will see that whenever the BDD algorithm attempts to create a @(see
 term) that is not a @(see BDD) term, it aborts instead.  Thus, whenever the
 algorithm completes without aborting, it creates a @(see BDD) term.</p>

 <p>(A3) <i>Canonical BDD terms</i></p>

 <p>We can strengthen the notion of ``BDD term'' to a notion of ``canonical BDD
 term'' by imposing the following additional requirements, for every subterm of
 the form @('(IF x y z)'):</p>

 <blockquote><p>(a) @('x') is a variable, and it precedes (in the BDD term
 order) every variable occurring in @('y') or @('z');</p>

 <p>(b) @('y') and @('z') are syntactically distinct; and,</p>

 <p>(c) it is not the case that @('y') is @('t') and @('z') is
 @('nil').</p></blockquote>

 <p>We claim that it follows easily from our description of the BDD algorithm
 that every term it creates is a canonical BDD term, assuming that the
 variables occurring in all such terms are treated by the algorithm as being
 Boolean (see (B2) below) and that the terms contain no function symbols other
 than @('IF') and @('CONS').  Thus, under those assumptions the following
 theorem shows that the BDD algorithm never creates distinct terms that are
 provably equal, a property that is useful for completeness and efficiency (as
 we explain in (B5) and (B6) below).</p>

 <p>(A4) <i>Provably equal canonical BDD terms are identical</i></p>

 <p>We believe that the following theorem and proof are routine extensions of a
 standard result and proof to terms that allow calls of @('CONS').</p>

 <p><b>Theorem</b>.  Suppose that @('t1') and @('t2') are canonical BDD terms
 that contain no function symbols other than @('IF') and @('CONS').  Also
 suppose that @('(EQUAL t1 t2)') is a theorem.  Then @('t1') and @('t2') are
 syntactically identical.</p>

 <p>Proof of theorem: By induction on the total number of symbols occurring in
 these two terms.  First suppose that at least one term is a variable; without
 loss of generality let it be @('t1').  We must prove that @('t2') is
 syntactically the same as @('t1').  Now it is clearly consistent that
 @('(EQUAL t1 t2)') is false if @('t2') is a call of @('CONS') (to see this,
 simply let @('t1') be an value that is not a @('CONSP')).  Similarly, @('t2')
 cannot be a constant or a variable other than @('t1').  The remaining
 possibility to rule out is that @('t2') is of the form @('(IF t3 t4 t5)'),
 since by assumption its function symbol must be @('IF') or @('CONS') and we
 have already handled the latter case.  Since @('t2') is canonical, we know
 that @('t3') is a variable.  Since @('(EQUAL t1 t2)') is provable, i.e.,</p>

 @({
  (EQUAL t1 (if t3 t4 t5))
 })

 <p>is provable, it follows that we may substitute either @('t') or @('nil')
 for @('t3') into this equality to obtain two new provable equalities.  First,
 suppose that @('t1') and @('t3') are distinct variables.  Then these
 substitutions show that @('t1') is provably equal to both @('t4') and @('t5')
 (since @('t3') does not occur in @('t4') or @('t5') by property (a) above, as
 @('t2') is canonical), and hence @('t4') and @('t5') are provably equal to
 each other, which implies by the inductive hypothesis that they are the same
 term &mdash; and this contradicts the assumption that @('t2') is canonical
 (property (b)).  Therefore @('t1') and @('t3') are the same variable, i.e.,
 the equality displayed above is actually @('(EQUAL t1 (if t1 t4 t5))').
 Substituting @('t') and then @('nil') for @('t1') into this provable equality
 lets us prove @('(EQUAL t t4)') and @('(EQUAL nil t5)'), which by the
 inductive hypothesis implies that @('t4') is (syntactically) the term @('t')
 and @('t5') is @('nil').  That is, @('t2') is @('(IF t1 t nil)'), which
 contradicts the assumption that @('t2') is canonical (property (c)).</p>

 <p>Next, suppose that at least one term is a call of @('IF').  Our first
 observation is that the other term is also a call of @('IF').  For if the
 other is a call of @('CONS'), then they cannot be provably equal, because the
 former has no function symbols other than @('IF') and hence is Boolean when
 all its variables are assigned Boolean values.  Also, if the other is a
 constant, then both branches of the @('IF') term are provably equal to that
 constant and hence these branches are syntactically identical by the inductive
 hypothesis, contradicting property (b).  Hence, we may assume for this case
 that both terms are calls of @('IF'); let us write them as follows.</p>

 @({
  t0:  (IF t1 t2 t3)
  u0:  (IF u1 u2 u3)
 })

 <p>Note that @('t1') and @('u1') are variables, by property (a) of canonical
 BDD terms.  First we claim that @('t1') does not strictly precede @('u1') in
 the BDD term order.  For suppose @('t1') does strictly precede @('u1').  Then
 property (a) of canonical BDD terms guarantees that @('t1') does not occur in
 @('u0').  Hence, an argument much like one used above shows that @('u0') is
 provably equal to both @('t2') (substituting @('t') for @('t1')) and @('t3')
 (substituting @('nil') for @('t1')), and hence @('t2') and @('t3') are
 provably equal.  That implies that they are identical terms, by the inductive
 hypothesis, which then contradicts property (b) for @('t0').  Similarly,
 @('u1') does not strictly precede @('t1') in the BDD term order.  Therefore,
 @('t1') and @('u1') are the same variable.  By substituting @('t') for this
 variable we see that @('t2') and @('u2') are provably equal, and hence they
 are equal by the inductive hypothesis.  Similarly, by substituting @('nil')
 for @('t1') (and @('u1')) we see that @('t3') and @('u3') are provably, hence
 syntactically, equal.</p>

 <p>We have covered all cases in which at least one term is a variable or at
 least one term is a call of @('IF').  If both terms are constants, then
 provable and syntactic equality are clearly equivalent.  Finally, then, we may
 assume that one term is a call of @('CONS') and the other is a constant or a
 call of @('CONS').  The constant case is similar to the @('CONS') case if the
 constant is a @('CONSP'), so we omit it; while if the constant is not a
 @('CONSP') then it is not provably equal to a call of @('CONS'); in fact it is
 provably <i>not</i> equal!</p>

 <p>So, we are left with a final case, in which canonical BDD terms @('(CONS t1
 t2)') and @('(CONS u1 u2)') are provably equal, and we want to show that
 @('t1') and @('u1') are syntactically equal as are @('t2') and @('u2').  These
 conclusions are easy consequences of the inductive hypothesis, since the ACL2
 axiom @('CONS-EQUAL') (which you can inspect using @(':')@(tsee PE)) shows
 that equality of the given terms is equivalent to the conjunction of @('(EQUAL
 t1 t2)') and @('(EQUAL u1 u2)').  Q.E.D.</p>

 <p>(B) <b>Algorithmic Considerations</b></p>

 <p>(B1) <i>BDD rules</i></p>

 <p>A rule of class @(':')@(tsee rewrite) (see @(see rule-classes)) is said to
 be a ``@(see BDD) rewrite rule'' if and only if it satisfies the following
 criteria.  (1) The rule is @(see enable)d.  (2) Its @(see equivalence)
 relation is @(tsee equal).  (3) It has no hypotheses.  (4) Its @(':')@(tsee
 loop-stopper) field is @('nil'), i.e., it is not a permutative rule.  (5) All
 variables occurring in the rule occur in its left-hand side (i.e., there are
 no ``free variables''; see @(see rewrite)).  A rule of class @(':')@(tsee
 definition) (see @(see rule-classes)) is said to be a ``@(see BDD) definition
 rule'' if it satisfies all the criteria above (except (4), which does not
 apply), and moreover the top function symbol of the left-hand side was not
 recursively (or mutually recursively) defined.  Technical point: Note that
 this additional criterion is independent of whether or not the indicated
 function symbol actually occurs in the right-hand side of the rule.</p>

 <p>Both BDD rewrite rules and BDD definition rules are said to be ``BDD
 rules.''</p>

 <p>(B2) <i>Terms ''known to be Boolean''</i></p>

 <p>We apply the BDD algorithm in the context of a top-level goal to prove,
 namely, the goal at which the @(':BDD') hint is attached.  As we run the BDD
 algorithm, we allow ourselves to say that a set of @(see term)s is ``known to
 be Boolean'' if we can verify that the goal is provable from the assumption
 that at least one of the terms is not Boolean.  Equivalently, we allow
 ourselves to say that a set of terms is ``known to be Boolean'' if we can
 verify that the original goal is provably equivalent to the assertion that if
 all terms in the set are Boolean, then the goal holds.  The notion ``known to
 be Boolean'' is conservative in the sense that there are generally sets of
 terms for which the above equivalent criteria hold and yet the sets of terms
 are not noted as as being ``known to be Boolean.''  However, ACL2 uses a
 number of tricks, including @(see type-reasoning) and analysis of the
 structure of the top-level goal, to attempt to establish that a sufficiently
 inclusive set of terms is known to be Boolean.</p>

 <p>From a practical standpoint, the algorithm determines a set of terms known
 to be Boolean; we allow ourselves to say that each term in this set is ``known
 to be Boolean.''  The algorithm assumes that these terms are indeed Boolean,
 and can make use of that assumption.  For example, if @('t1') is known to be
 Boolean then the algorithm simplifies @('(IF t1 t nil)') to @('t1'); see (iv)
 in the discussion immediately below.</p>

 <p>(B3) <i>IF-lifting</i> and the <i>IF-lifting-for-IF loop</i></p>

 <p>Suppose that one has a @(see term) of the form @('(f ... (IF test x y)
 ...)'), where @('f') is a function symbol other than @('CONS').  Then we say
 that ``IF-lifting'' @('test') ``from'' this term produces the following term,
 which is provably equal to the given term.</p>

 @({
  (if test
      (f ... x ...)  ; resulting true branch
      (f ... y ...)) ; resulting false branch
 })

 <p>Here, we replace each argument of @('f') of the form @('(IF test .. ..)'),
 for the same @('test'), in the same way.  In this case we say that
 ``IF-lifting applies to'' the given term, ``yielding the test'' @('test') and
 with the ``resulting two branches'' displayed above.  Whenever we apply
 IF-lifting, we do so for the available @('test') that is least in the BDD term
 order (see (A1) above).</p>

 <p>We consider arguments @('v') of @('f') that are ``known to be Boolean''
 (see above) to be replaced by @('(IF v t nil)') for the purposes of
 IF-lifting, i.e., before IF-lifting is applied.</p>

 <p>There is one special case, however, for IF-lifting.  Suppose that the given
 term is of the form @('(IF v y z)') where @('v') is a variable and is the test
 to be lifted out (i.e., it is least in the BDD term order among the potential
 tests).  Moreover, suppose that neither @('y') nor @('z') is of the form
 @('(IF v W1 W2)') for that same @('v').  Then IF-lifting does not apply to the
 given term.</p>

 <p>We may now describe the IF-lifting-for-IF loop, which applies to terms of
 the form @('(IF test tbr fbr)') where the algorithm has already produced
 @('test'), @('tbr'), and @('fbr').  First, if @('test') is @('nil') then we
 return @('fbr'), while if @('test') is a non-@('nil') constant or a call of
 @('CONS') then we return @('tbr').  Otherwise, we see if IF-lifting applies.
 If IF-lifting does not apply, then we return @('(IF test tbr fbr)').
 Otherwise, we apply IF-lifting to obtain a term of the form @('(IF x y z)'),
 by lifting out the appropriate test.  Now we recursively apply the
 IF-lifting-for-IF loop to the term @('(IF x y z)'), unless any of the
 following special cases apply.</p>

 <blockquote><p>(i) If @('y') and @('z') are the same term, then return
 @('y').</p>

 <p>(ii) Otherwise, if @('x') and @('z') are the same term, then replace @('z')
 by @('nil') before recursively applying IF-lifting-for-IF.</p>

 <p>(iii) Otherwise, if @('x') and @('y') are the same term and @('y') is known
 to be Boolean, then replace @('y') by @('t') before recursively applying
 IF-lifting-for-IF.</p>

 <p>(iv) If @('z') is @('nil') and either @('x') and @('y') are the same term
 or @('x') is ``known to be Boolean'' and @('y') is @('t'), then return
 @('x').</p></blockquote>

 <p>NOTE: When a variable @('x') is known to be Boolean, it is easy to see that
 the form @('(IF x t nil)') is always reduced to @('x') by this algorithm.</p>

 <p>(B4) <i>The ACL2 BDD algorithm</i></p>

 <p>We are now ready to present the BDD algorithm for ACL2.  It is given an
 ACL2 @(see term), @('x'), as well as an association list @('va') that maps
 variables to terms, including all variables occurring in @('x').  We maintain
 the invariant that whenever a variable is mapped by @('va') to a term, that
 term has already been constructed by the algorithm, except: initially @('va')
 maps every variable occurring in the top-level term to itself.  The algorithm
 proceeds as follows.  We implicitly ordain that whenever the BDD algorithm
 attempts to create a @(see term) that is not a @(see BDD) term (as defined
 above in (A2)), it aborts instead.  Thus, whenever the algorithm completes
 without aborting, it creates a @(see BDD) term.</p>

 <blockquote>

 <p>If @('x') is a variable, return the result of looking it up in @('va').</p>

 <p>If @('x') is a constant, return @('x').</p>

 <p>If @('x') is of the form @('(IF test tbr fbr)'), then first run the
 algorithm on @('test') with the given @('va') to obtain @('test'').  If
 @('test'') is @('nil'), then return the result @('fbr'') of running the
 algorithm on @('fbr') with the given @('va').  If @('test'') is a constant
 other than @('nil'), or is a call of @('CONS'), then return the result
 @('tbr'') of running the algorithm on @('tbr') with the given @('va').  If
 @('tbr') is identical to @('fbr'), return @('tbr').  Otherwise, return the
 result of applying the IF-lifting-for-IF loop (described above) to the term
 <tt>(IF test' tbr' fbr')</tt>.</p>

 <p>If @('x') is of the form @('(IF* test tbr fbr)'), then compute the result
 exactly as though @(tsee IF) were used rather than @(tsee IF*), except that if
 @('test'') is not a constant or a call of @('CONS') (see paragraph above),
 then abort the BDD computation.  Informally, the tests of @(tsee IF*) terms
 are expected to ``resolve.''  NOTE: This description shows how @(tsee IF*) can
 be used to implement conditional rewriting in the BDD algorithm.</p>

 <p>If @('x') is a @('LAMBDA') expression @('((LAMBDA vars body) . args)')
 (which often corresponds to a @(tsee LET) term; see @(see let)), then first
 form an alist @('va'') by binding each @('v') in @('vars') to the result of
 running the algorithm on the corresponding member of @('args'), with the
 current alist @('va').  Then, return the result of the algorithm on @('body')
 in the alist @('va'').</p>

 <p>Otherwise, @('x') is of the form @('(f x1 x2 ... xn)'), where @('f') is a
 function symbol other than @(tsee IF) or @(tsee IF*).  In that case, let
 @('xi'') be the result of running the algorithm on @('xi'), for @('i') from 1
 to @('n'), using the given alist @('va').  First there are a few special
 cases.  If @('f') is @(tsee EQUAL) then we return @('t') if @('x1'') is
 syntactically identical to @('x2'') (where this test is very fast; see (B6)
 below); we return @('x1'') if it is known to be Boolean and @('x2'') is
 @('t'); and similarly, we return @('x2'') if it is known to be Boolean and
 @('x1'') is @('t').  Next, if each @('xi'') is a constant and the @(':')@(tsee
 executable-counterpart) of @('f') is enabled, then the result is obtained by
 computation.  Next, if @('f') is @(tsee BOOLEANP) and @('x1'') is known to be
 Boolean, @('t') is returned.  Otherwise, we proceed as follows, first possibly
 swapping the arguments if they are out of (the BDD term) order and if @('f')
 is known to be commutative (see below).  If a BDD rewrite rule (as defined
 above) matches the term <tt>(f x1'... xn')</tt>, then the most recently stored
 such rule is applied.  If there is no such match and @('f') is a
 BDD-constructor, then we return <tt>(f x1'... xn')</tt>.  Otherwise, if a BDD
 definition rule matches this term, then the most recently stored such rule
 (which will usually be the original definition for most users) is applied.  If
 none of the above applies and neither does IF-lifting, then we return <tt>(f
 x1'... xn')</tt>.  Otherwise we apply IF-lifting to <tt>(f x1'... xn')</tt> to
 obtain a term @('(IF test tbr fbr)'); but we aren't done yet.  Rather, we run
 the BDD algorithm (using the same alist) on @('tbr') and @('fbr') to obtain
 terms @('tbr'') and @('fbr''), and we return <tt>(IF test tbr' fbr')</tt>
 unless @('tbr'') is syntactically identical to @('fbr''), in which case we
 return @('tbr'').</p></blockquote>

 <p>When is it the case that, as said above, ``@('f') is known to be
 commutative''?  This happens when an enabled rewrite rule is of the form
 @('(EQUAL (f X Y) (f Y X))').  Regarding swapping the arguments in that case:
 recall that we may assume very little about the BDD term order, essentially
 only that we swap the two arguments when the second is a constant and the
 first is not, for example, in @('(+ x 1)').  Other than that situation, one
 cannot expect to predict accurately when the arguments of commutative
 operators will be swapped.</p>

 <p>(B5) Soundness and Completeness of the ACL2 BDD algorithm</p>

 <p>Roughly speaking, ``soundness'' means that the BDD algorithm should give
 correct answers, and ``completeness'' means that it should be powerful enough
 to prove all true facts.  Let us make the soundness claim a little more
 precise, and then we'll address completeness under suitable hypotheses.</p>

 <p><b>Claim</b> (Soundness).  If the ACL2 BDD algorithm runs to completion on
 an input term @('t0'), then it produces a result that is provably equal to
 @('t0').</p>

 <p>We leave the proof of this claim to the reader.  The basic idea is simply
 to check that each step of the algorithm preserves the meaning of the term
 under the bindings in the given alist.</p>

 <p>Let us start our discussion of completeness by recalling the theorem proved
 above in (A4).</p>

 <p><b>Theorem</b>.  Suppose that @('t1') and @('t2') are canonical BDD terms
 that contain no function symbols other than @('IF') and @('CONS').  Also
 suppose that @('(EQUAL t1 t2)') is a theorem.  Then @('t1') and @('t2') are
 syntactically identical.</p>

 <p>Below we show how this theorem implies the following completeness property
 of the ACL2 BDD algorithm.  We continue to assume that @('CONS') is the only
 BDD-constructor.</p>

 <p><b>Claim</b> (Completeness).  Suppose that @('t1') and @('t2') are provably
 equal terms, under the assumption that all their variables are known to be
 Boolean.  Assume further that under this same assumption, top-level runs of
 the ACL2 BDD algorithm on these terms return terms that contain only the
 function symbols @('IF') and @('CONS').  Then the algorithm returns the same
 term for both @('t1') and @('t2'), and the algorithm reduces @('(EQUAL t1
 t2)') to @('t').</p>

 <p>Why is this claim true?  First, notice that the second part of the
 conclusion follows immediately from the first, by definition of the algorithm.
 Next, notice that the terms @('u1') and @('u2') obtained by running the
 algorithm on @('t1') and @('t2'), respectively, are provably equal to @('t1')
 and @('t2'), respectively, by the Soundness Claim.  It follows that @('u1')
 and @('u2') are provably equal to each other.  Since these terms contain no
 function symbols other than @('IF') or @('CONS'), by hypothesis, the Claim now
 follows from the Theorem above together with the following lemma.</p>

 <p><b>Lemma</b>.  Suppose that the result of running the ACL2 BDD algorithm on
 a top-level term @('t0') is a term @('u0') that contains only the function
 symbols @('IF') and @('CONS'), where all variables of @('t0') are known to be
 Boolean.  Then @('u0') is a canonical BDD term.</p>

 <p>Proof: left to the reader.  Simply follow the definition of the algorithm,
 with a separate argument for the IF-lifting-for-IF loop.</p>

 <p>Finally, let us remark on the assumptions of the Completeness Claim above.
 The assumption that all variables are known to be Boolean is often true; in
 fact, the system uses the forward-chaining rule @('boolean-listp-forward')
 (you can see it using @(':')@(tsee pe)) to try to establish this assumption,
 if your theorem has a form such as the following.</p>

 @({
  (let ((x (list x0 x1 ...))
        (y (list y0 y1 ...)))
    (implies (and (boolean-listp x)
                  (boolean-listp y))
             ...))
 })

 <p>Moreover, the @(':BDD') hint can be used to force the prover to abort if it
 cannot check that the indicated variables are known to be Boolean; see @(see
 hints).</p>

 <p>Finally, consider the effect in practice of the assumption that the terms
 resulting from application of the algorithm contain calls of @('IF') and
 @('CONS') only.  Typical use of BDDs in ACL2 takes place in a theory (see
 @(see theories)) in which all relevant non-recursive function symbols are
 enabled and all recursive function symbols possess enabled BDD rewrite rules
 that tell them how open up.  For example, such a rule may say how to expand on
 a given function call's argument that has the form @('(CONS a x)'), while
 another may say how to expand when that argument is @('nil')).  (See for
 example the rules @('append-cons') and @('append-nil') in the documentation
 for @(tsee IF*).)  We leave it to future work to formulate a theorem that
 guarantees that the BDD algorithm produces terms containing calls only of
 @('IF') and @('CONS') assuming a suitably ``complete'' collection of rewrite
 rules.</p>

 <p>(B6) <i>Efficiency considerations</i></p>

 <p>Following Bryant's algorithm, we use a graph representation of @(see term)s
 created by the BDD algorithm's computation.  This representation enjoys some
 important properties.</p>

 <blockquote>

 <p>(Time efficiency) The test for syntactic equality of BDD terms is very
 fast.</p>

 <p>(Space efficiency) Equal BDD data structures are stored identically in
 memory.</p></blockquote>

 <p><i>Implementation note.</i> The representation actually uses a sort of hash
 table for BDD terms that is implemented as an ACL2 1-dimensional array.  See
 @(see arrays).  In addition, we use a second such hash table to avoid
 recomputing the result of applying a function symbol to the result of running
 the algorithm on its arguments.  We believe that these uses of hash tables are
 standard.  They are also discussed in Moore's paper on BDDs; see @(see bdd)
 for the reference.</p>")

(defxdoc bdd-introduction
  :parents (bdd)
  :short "Examples illustrating the use of BDDs in ACL2"
  :long "<p>See @(see bdd) for a brief introduction to BDDs in ACL2 and for
 pointers to other documentation on BDDs in ACL2.  Here, we illustrate the use
 of BDDs in ACL2 by way of some examples.  For a further example, see @(see
 if*).</p>

 <p>Let us begin with a really simple example.  (We will explain the @(':bdd')
 hint @('(:vars nil)') below.)</p>

 @({
  ACL2 !>(thm (equal (if a b c) (if (not a) c b))
              :hints (("Goal" :bdd (:vars nil)))) ; Prove with BDDs

  [Note:  A hint was supplied for the goal above.  Thanks!]

  But simplification with BDDs (7 nodes) reduces this to T, using the
  :definitions EQUAL and NOT.

  Q.E.D.

  Summary
  Form:  ( THM ...)
  Rules: ((:DEFINITION EQUAL) (:DEFINITION NOT))
  Warnings:  None
  Time:  0.18 seconds (prove: 0.05, print: 0.02, other: 0.12)

  Proof succeeded.
  ACL2 !>
 })

 <p>The @(':bdd') hint @('(:vars nil)') indicates that BDDs are to be used on
 the indicated goal, and that any so-called ``variable ordering'' may be used:
 ACL2 may use a convenient order that is far from optimal.  It is beyond the
 scope of the present documentation to address the issue of how the user may
 choose good variable orderings.  Someday our implementation of BDDs may be
 improved to include heuristically-chosen variable orderings rather than rather
 random ones.</p>

 <p>Here is a more interesting example.</p>

 @({
  (defun v-not (x)
  ; Complement every element of a list of Booleans.
    (if (consp x)
        (cons (not (car x)) (v-not (cdr x)))
      nil))

  ; Now we prove a rewrite rule that explains how to open up v-not on
  ; a consp.
  (defthm v-not-cons
    (equal (v-not (cons x y))
           (cons (not x) (v-not y))))

  ; Finally, we prove for 7-bit lists that v-not is self-inverting.
  (thm
   (let ((x (list x0 x1 x2 x3 x4 x5 x6)))
     (implies (boolean-listp x)
              (equal (v-not (v-not x)) x)))
   :hints (("Goal" :bdd
                   ;; Note that this time we specify a variable order.
                   (:vars (x0 x1 x2 x3 x4 x5 x6)))))
 })

 <p>It turns out that the variable order doesn't seem to matter in this
 example; using several orders we found that 30 nodes were created, and the
 proof time was about 1/10 of a second on a (somewhat enhanced) Sparc 2.  The
 same proof took about a minute and a half without any @(':bdd') hint!  This
 observation is a bit misleading perhaps, since the theorem for arbitrary
 @('x'),</p>

 @({
  (thm
   (implies (boolean-listp x)
            (equal (v-not (v-not x)) x)))
 })

 <p>only takes about 1.5 times as long as the @(':bdd') proof for 7 bits,
 above!  Nevertheless, BDDs can be very useful in reducing proof time,
 especially when there is no regular structure to facilitate proof by
 induction, or when the induction scheme is so complicated to construct that
 significant user effort is required to get the proof by induction to go
 through.</p>

 <p>Finally, consider the preceding example, with a @(':bdd') hint of (say)
 @('(:vars nil)'), but with the rewrite rule @('v-not-cons') above disabled.
 In that case, the proof fails, as we see below.  That is because the BDD
 algorithm in ACL2 uses hypothesis-free @(':')@(see rewrite) rules,
 @(':')@(tsee executable-counterpart)@('s'), and nonrecursive definitions, but
 it does not use recursive definitions.</p>

 <p>Notice that when we issue the @('(show-bdd)') command, the system's
 response clearly shows that we need a rewrite rule for simplifying terms of
 the form @('(v-not (cons ...))').</p>

 @({
  ACL2 !>(thm
          (let ((x (list x0 x1 x2 x3 x4 x5 x6)))
            (implies (boolean-listp x)
                     (equal (v-not (v-not x)) x)))
          :hints (("Goal" :bdd (:vars nil)
                   :in-theory (disable v-not-cons))))

  [Note:  A hint was supplied for the goal above.  Thanks!]

  ACL2 Error in ( THM ...):  Attempted to create V-NOT node during BDD
  processing with an argument that is a call of a bdd-constructor,
  which would produce a non-BDD term (as defined in :DOC
  bdd-algorithm).  See :DOC show-bdd.

  Summary
  Form:  ( THM ...)
  Rules: NIL
  Warnings:  None
  Time:  0.58 seconds (prove: 0.13, print: 0.00, other: 0.45)

  ******** FAILED ********  See :DOC failure  ******** FAILED ********
  ACL2 !>(show-bdd)

  BDD computation on Goal yielded 17 nodes.
  ------------------------------

  BDD computation was aborted on Goal, and hence there is no
  falsifying assignment that can be constructed.  Here is a backtrace
  of calls, starting with the top-level call and ending with the one
  that led to the abort.  See :DOC show-bdd.

  (LET ((X (LIST X0 X1 X2 X3 X4 X5 ...)))
       (IMPLIES (BOOLEAN-LISTP X)
                (EQUAL (V-NOT (V-NOT X)) X)))
    alist: ((X6 X6) (X5 X5) (X4 X4) (X3 X3) (X2 X2) (X1 X1) (X0 X0))

  (EQUAL (V-NOT (V-NOT X)) X)
    alist: ((X (LIST X0 X1 X2 X3 X4 X5 ...)))

  (V-NOT (V-NOT X))
    alist: ((X (LIST X0 X1 X2 X3 X4 X5 ...)))

  (V-NOT X)
    alist: ((X (LIST X0 X1 X2 X3 X4 X5 ...)))
  ACL2 !>
 })

 <p>The term that has caused the BDD algorithm to abort is thus @('(V-NOT X)'),
 where @('X') has the value @('(LIST X0 X1 X2 X3 X4 X5 ...)'), i.e., @('(CONS
 X0 (LIST X1 X2 X3 X4 X5 ...))').  Thus, we see the utility of introducing a
 rewrite rule to simplify terms of the form @('(V-NOT (CONS ...))').  The moral
 of this story is that if you get an error of the sort shown above, you may
 find it useful to execute the command @('(show-bdd)') and use the result as
 advice that suggests the left hand side of a rewrite rule.</p>

 <p>Here is another sort of failed proof.  In this version we have omitted the
 hypothesis that the input is a bit vector.  Below we use @('show-bdd') to see
 what went wrong, and use the resulting information to construct a
 counterexample.  This failed proof corresponds to a slightly modified input
 theorem, in which @('x') is bound to the 4-element list @('(list x0 x1 x2
 x3)').</p>

 @({
  ACL2 !>(thm
          (let ((x (list x0 x1 x2 x3)))
            (equal (v-not (v-not x)) x))
          :hints (("Goal" :bdd
                   ;; This time we do not specify a variable order.
                   (:vars nil))))

  [Note:  A hint was supplied for the goal above.  Thanks!]

  ACL2 Error in ( THM ...):  The :BDD hint for the current goal has
  successfully simplified this goal, but has failed to prove it.
  Consider using (SHOW-BDD) to suggest a counterexample; see :DOC
  show-bdd.

  Summary
  Form:  ( THM ...)
  Rules: NIL
  Warnings:  None
  Time:  0.18 seconds (prove: 0.07, print: 0.00, other: 0.12)

  ******** FAILED ********  See :DOC failure  ******** FAILED ********
  ACL2 !>(show-bdd)

  BDD computation on Goal yielded 73 nodes.
  ------------------------------

  Falsifying constraints:
  ((X0 "Some non-nil value")
   (X1 "Some non-nil value")
   (X2 "Some non-nil value")
   (X3 "Some non-nil value")
   ((EQUAL 'T X0) T)
   ((EQUAL 'T X1) T)
   ((EQUAL 'T X2) T)
   ((EQUAL 'T X3) NIL))

  ------------------------------

  Term obtained from BDD computation on Goal:

  (IF X0
      (IF X1
          (IF X2 (IF X3 (IF # # #) (IF X3 # #))
              (IF X2 'NIL (IF X3 # #)))
          (IF X1 'NIL
              (IF X2 (IF X3 # #) (IF X2 # #))))
      (IF X0 'NIL
          (IF X1 (IF X2 (IF X3 # #) (IF X2 # #))
              (IF X1 'NIL (IF X2 # #)))))

  ACL2 Query (:SHOW-BDD):  Print the term in full?  (N, Y, W or ?):
  n ; I've seen enough.  The assignment shown above suggests
    ; (though not conclusively) that if we bind x3 to a non-nil
    ; value other than T, and bind x0, x1, and x2 to t, then we
    ; this may give us a counterexample.
  ACL2 !>(let ((x0 t) (x1 t) (x2 t) (x3 7))
           (let ((x (list x0 x1 x2 x3)))
             ;; Let's use LIST instead of EQUAL to see how the two
             ;; lists differ.
             (list (v-not (v-not x)) x)))
  ((T T T T) (T T T 7))
  ACL2 !>
 })

 <p>See @(see if*) for another example.</p>")

(defxdoc binary-*
  :parents (* acl2-built-ins)
  :short "Multiplication function"
  :long "<p>Completion Axiom (@('completion-of-*')):</p>

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

 <p>@(see Guard) for @('(binary-* x y)'):</p>

 @({
  (and (acl2-numberp x) (acl2-numberp y))
 })

 <p>Notice that like all arithmetic functions, @('binary-*') treats non-numeric
 inputs as @('0').</p>

 <p>Calls of the macro @(tsee *) expand to calls of @('binary-*'); see @(see
 *).</p>")

(defxdoc binary-+
  :parents (+ acl2-built-ins)
  :short "Addition function"
  :long "<p>Completion Axiom (@('completion-of-+')):</p>

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

 <p>@(see Guard) for @('(binary-+ x y)'):</p>

 @({
  (and (acl2-numberp x) (acl2-numberp y))
 })

 <p>Notice that like all arithmetic functions, @('binary-+') treats non-numeric
 inputs as @('0'). Thus, the following are theorems.</p>

 @({
  (thm (equal (+ (fix x) y) (+ x y)))
  (thm (equal (+ x (fix y)) (+ x y)))
 })

 <p>Calls of the macro @(tsee +) expand to calls of @('binary-+'); see @(see
 +).</p>")

(defxdoc binary-append
  :parents (append acl2-built-ins)
  :short "@(see concatenate) two lists"
  :long "<p>This binary function implements @(tsee append), which is a macro in
 ACL2.  See @(see append)</p>

 <p>The @(see guard) for @('binary-append') requires the first argument to be a
 @(tsee true-listp).</p>

 @(def binary-append)")

(defxdoc bind-free
  :parents (rewrite linear definition)
  :short "To bind free variables of a rewrite, definition, or linear rule"
  :long "@({
  Examples:
  (IMPLIES (AND (RATIONALP LHS)
                (RATIONALP RHS)
                (BIND-FREE (FIND-MATCH-IN-PLUS-NESTS LHS RHS) (X)))
           (EQUAL (EQUAL LHS RHS)
                  (EQUAL (+ (- X) LHS) (+ (- X) RHS))))

  (IMPLIES (AND (BIND-FREE
                  (FIND-RATIONAL-MATCH-IN-TIMES-NESTS LHS RHS MFC STATE)
                  (X))
                (RATIONALP X)
                (CASE-SPLIT (NOT (EQUAL X 0))))
           (EQUAL (< LHS RHS)
                  (IF (< 0 X)
                      (< (* (/ X) LHS) (* (/ X) RHS))
                     (< (* (/ X) RHS) (* (/ X) LHS)))))
 })

 <p>General Forms:</p>

 @({
  (BIND-FREE term var-list)
  (BIND-FREE term t)
  (BIND-FREE term)
 })

 <p>A rule which uses a @('bind-free') hypothesis has similarities to both a
 rule which uses a @(tsee syntaxp) hypothesis and to a @(':')@(tsee meta) rule.
 @('Bind-free') is like @(tsee syntaxp), in that it logically always returns
 @('t') but may affect the application of a @(':')@(tsee rewrite), @(':')@(tsee
 rewrite-quoted-constant), @(':')@(tsee definition), or @(':')@(tsee linear)
 rule when it is called at the top-level of a hypothesis.  It is like a
 @(':')@(tsee meta) rule, in that it allows the user to perform transformations
 of terms under programmatic control.</p>

 <p>Note that a @('bind-free') hypothesis does not, in general, deal with the
 meaning or semantics or values of the terms, but rather with their syntactic
 forms.  Before attempting to write a rule which uses @('bind-free'), the user
 should be familiar with @(tsee syntaxp) and the internal form that ACL2 uses
 for terms.  This internal form is similar to what the user sees, but there are
 subtle and important differences.  @(tsee Trans) can be used to view this
 internal form.</p>

 <p>Just as for a @(tsee syntaxp) hypothesis, there are two basic types of
 @('bind-free') hypotheses.  The simpler type of @('bind-free') hypothesis may
 be used as the nth hypothesis in a @(':')@(tsee rewrite), @(':')@(tsee
 definition), or @(':')@(tsee linear) rule whose @(':')@(tsee corollary) is
 @('(implies (and hyp1 ... hypn ... hypk) (equiv lhs rhs))') provided @('term')
 is a term, @('term') contains at least one variable, and every variable
 occurring freely in @('term') occurs freely in @('lhs') or in some @('hypi'),
 @('i<n').  In addition, @('term') must not use any stobjs.  Later below we
 will describe the second type, an <i>extended</i> @('bind-free') hypothesis,
 which is similar except that it may use @(tsee state) and @(tsee mfc).
 Whether simple or extended, a @('bind-free') hypothesis may return an alist
 that binds free variables, as explained below, or it may return a list of such
 alists.  We focus on the first of these cases: return of a single binding
 alist.  We conclude our discussion with a section that covers the other case:
 return of a list of alists.</p>

 <p>We begin our description of @('bind-free') by examining the first example
 above in some detail.</p>

 <p>We wish to write a rule which will cancel ``like'' addends from both sides
 of an equality.  Clearly, one could write a series of rules such as</p>

 @({
  (DEFTHM THE-HARD-WAY-2-1
     (EQUAL (EQUAL (+ A X B)
                   (+ X C))
            (EQUAL (+ A B)
                   (FIX C))))
 })

 <p>with one rule for each combination of positions the matching addends might
 be found in (if one knew before-hand the maximum number of addends that would
 appear in a sum).  But there is a better way.  (In what follows, we assume the
 presence of an appropriate set of rules for simplifying sums.)</p>

 <p>Consider the following definitions and theorem:</p>

 @({
  (DEFUN INTERSECTION-EQUAL (X Y)
    (COND ((ENDP X)
           NIL)
          ((MEMBER-EQUAL (CAR X) Y)
           (CONS (CAR X) (INTERSECTION-EQUAL (CDR X) Y)))
          (T
           (INTERSECTION-EQUAL (CDR X) Y))))

  (DEFUN PLUS-LEAVES (TERM)
    (IF (EQ (FN-SYMB TERM) 'BINARY-+)
        (CONS (FARGN TERM 1)
              (PLUS-LEAVES (FARGN TERM 2)))
      (LIST TERM)))

  (DEFUN FIND-MATCH-IN-PLUS-NESTS (LHS RHS)
    (IF (AND (EQ (FN-SYMB LHS) 'BINARY-+)
             (EQ (FN-SYMB RHS) 'BINARY-+))
        (LET ((COMMON-ADDENDS (INTERSECTION-EQUAL (PLUS-LEAVES LHS)
                                                  (PLUS-LEAVES RHS))))
          (IF COMMON-ADDENDS
              (LIST (CONS 'X (CAR COMMON-ADDENDS)))
            NIL))
      NIL))

  (DEFTHM CANCEL-MATCHING-ADDENDS-EQUAL
    (IMPLIES (AND (RATIONALP LHS)
                  (RATIONALP RHS)
                  (BIND-FREE (FIND-MATCH-IN-PLUS-NESTS LHS RHS) (X)))
             (EQUAL (EQUAL LHS RHS)
                    (EQUAL (+ (- X) LHS) (+ (- X) RHS)))))
 })

 <p>How is this rule applied to the following term?</p>

 @({
  (equal (+ 3 (expt a n) (foo a c))
         (+ (bar b) (expt a n)))
 })

 <p>As mentioned above, the internal form of an ACL2 term is not always what
 one sees printed out by ACL2.  In this case, by using @(':')@(tsee trans) one
 can see that the term is stored internally as</p>

 @({
  (equal (binary-+ '3
                   (binary-+ (expt a n) (foo a c)))
         (binary-+ (bar b) (expt a n))).
 })

 <p>When ACL2 attempts to apply @('cancel-matching-addends-equal') to the term
 under discussion, it first forms a substitution that instantiates the
 left-hand side of the conclusion so that it is identical to the target term.
 This substitution is kept track of by the substitution alist:</p>

 @({
  ((LHS . (binary-+ '3
                     (binary-+ (expt a n) (foo a c))))
   (RHS . (binary-+ (bar b) (expt a n)))).
 })

 <p>ACL2 then attempts to relieve the hypotheses in the order they were given.
 Ordinarily this means that we instantiate each hypothesis with our
 substitution and then attempt to rewrite the resulting instance to true.
 Thus, in order to relieve the first hypothesis, we rewrite:</p>

 @({
  (RATIONALP (binary-+ '3
                        (binary-+ (expt a n) (foo a c)))).
 })

 <p>Let us assume that the first two hypotheses rewrite to @('t').  How do we
 relieve the @('bind-free') hypothesis?  Just as for a @(tsee syntaxp)
 hypothesis, ACL2 evaluates @('(find-match-in-plus-nests lhs rhs)') in an
 environment where @('lhs') and @('rhs') are instantiated as determined by the
 substitution.  In this case we evaluate</p>

 @({
  (FIND-MATCH-IN-PLUS-NESTS '(binary-+ '3
                                        (binary-+ (expt a n) (foo a c)))
                            '(binary-+ (bar b) (expt a n))).
 })

 <p>Observe that, just as in the case of a @(tsee syntaxp) hypothesis, we
 substitute the quotation of the variables bindings into the term to be
 evaluated.  See @(see syntaxp) for the reasons for this.  The result of this
 evaluation, @('((X . (EXPT A N)))'), is then used to extend the substitution
 alist:</p>

 @({
  ((X . (EXPT A N))
   (LHS . (binary-+ '3
                     (binary-+ (expt a n) (foo a c))))
   (RHS . (binary-+ (bar b) (expt a n)))),
 })

 <p>and this extended substitution determines
 @('cancel-matching-addends-equal')'s result:</p>

 @({
  (EQUAL (+ (- X) LHS) (+ (- X) RHS))
  ==>
  (EQUAL (+ (- (EXPT A N)) 3 (EXPT A N) (FOO A C))
         (+ (- (EXPT A N)) (BAR B) (EXPT A N))).
 })

 <p>Question: What is the internal form of this result?<br></br>

 Hint: Use @(':')@(tsee trans).</p>

 <p>When this rule fires, it adds the negation of a common term to both sides
 of the equality by selecting a binding for the otherwise-free variable @('x'),
 under programmatic control.  Note that other mechanisms such as the binding of
 @(see free-variables) may also extend the substitution alist.</p>

 <p>Just as for a @(tsee syntaxp) test, a @('bind-free') form signals failure
 by returning @('nil').  However, while a @(tsee syntaxp) test signals success
 by returning true, a @('bind-free') form signals success by returning an alist
 which is used to extend the current substitution alist.  Because of this use
 of the alist, there are several restrictions on it &mdash; in particular the
 alist must only bind variables, these variables must not be already bound by
 the substitution alist, and the variables must be bound to ACL2 terms.  If
 @('term') returns an alist and the alist meets these restrictions, we append
 the alist to the substitution alist and use the result as the new current
 substitution alist.  This new current substitution alist is then used when we
 attempt to relieve the next hypothesis or, if there are no more, instantiate
 the right hand side of the rule.</p>

 <p>There is also a second, optional, @('var-list') argument to a
 @('bind-free') hypothesis.  If provided, it must be either @('t'), @('nil'),
 or a non-empty list of variables.  If it is not provided, it defaults to
 @('t'); and it is also treated as @('t') if the value provided is @('nil').
 If it is a non-empty list of variables, this second argument is used to place
 a further restriction on the possible values of the alist to be returned by
 @('term'): any variables bound in the alist must be present in that list of
 variables.  We strongly recommend the use of this list of variables, as that
 list is considered to contribute to the list of variables in the hypotheses of
 a linear rule; see @(see linear), in particular condition (b) mentioned there
 regarding a requirement that maximal terms and hypotheses must suffice for
 instantiating all the variables in the conclusion.  If @('var-list') is @('t')
 (either explicitly or implicitly, as described above), then that condition is
 considered to be met trivially; this could prevent ACL2 from rejecting
 ineffective linear rules.</p>

 <p>An extended @('bind-free') hypothesis is similar to the simple type
 described above, but it uses two additional variables, @('mfc') and
 @('state'), which must not be bound by the left hand side or an earlier
 hypothesis of the rule.  They must be the last two variables mentioned by
 @('term'): first @('mfc'), then @('state').  These two variables give access
 to the functions @('mfc-')xxx; see @(see extended-metafunctions).  As
 described there, @('mfc') is bound to the so-called metafunction-context and
 @('state') to ACL2's @(tsee state).  See @(see bind-free-examples) for
 examples of the use of these extended @('bind-free') hypotheses.</p>

 <p><b>SECTION</b>: Returning a list of alists.</p>

 <p>As promised above, we conclude with a discussion of the case that
 evaluation of the @('bind-free') term produces a list of alists, @('x'),
 rather than a single alist.  In this case each member @('b') of @('x') is
 considered in turn, starting with the first and proceeding through the list.
 Each such @('b') is handled exactly as discussed above, as though it were the
 result of evaluating the @('bind-free') term.  Thus, each @('b') extends the
 current variable binding alist, and all remaining hypotheses are then
 relieved, as though @('b') had been the value obtained by evaluating the
 @('bind-free') term.  As soon as one such @('b') leads to successful relieving
 of all remaining hypotheses, the process of relieving hypotheses concludes, so
 no further members of @('x') are considered.</p>

 <p>We illustrate with a simple pedagogical example.  First introduce functions
 @('p1') and @('p2') such that a rewrite rule specifies that @('p2') implies
 @('p1'), but with a free variable.</p>

 @({
  (defstub p1 (x) t)
  (defstub p2 (x y) t)

  (defaxiom p2-implies-p1
    (implies (p2 x y)
             (p1 x)))
 })

 <p>If we add the following axiom, then @('(p1 x)') follows logically for all
 @('x').</p>

 @({
  (defaxiom p2-instance
    (p2 v (cons v 4)))
 })

 <p>Unfortunately, evaluation of @('(thm (p1 a))') fails, because ACL2 fails to
 bind the free variable @('y') in order to apply the rule @('p2-instance').</p>

 <p>Let's define a function that produces a list of alists, each binding the
 variable @('y').  Of course, we know that only the middle one below is
 necessary in this simple example.  In more complex examples, one might use
 heuristics to construct such a list of alists.</p>

 @({
  (defun my-alists (x)
    (list (list (cons 'y (fcons-term* 'cons x ''3)))
          (list (cons 'y (fcons-term* 'cons x ''4)))
          (list (cons 'y (fcons-term* 'cons x ''5)))))
 })

 <p>The following rewrite rule uses @('bind-free') to return a list of
 candidate alists binding @('y').</p>

 @({
  (defthm p2-implies-p1-better
    (implies (and (bind-free (my-alists x)
                             (y)) ; the second argument, (y), is optional
                  (p2 x y))
             (p1 x)))
 })

 <p>Now the proof succeeds for @('(thm (p1 a))').  Why?  When ACL2 applies the
 @('rewrite') rule @('p2-implies-p1-better'), it evaluates @('my-alists'), as
 we can see from the following @(see trace), to bind @('y') in three different
 alists.</p>

 @({
  ACL2 !>(thm (p1 a))
  1> (ACL2_*1*_ACL2::MY-ALISTS A)
  <1 (ACL2_*1*_ACL2::MY-ALISTS (((Y CONS A '3))
                                ((Y CONS A '4))
                                ((Y CONS A '5))))

  Q.E.D.
 })

 <p>The first alist, binding @('y') to @('(cons a '3)'), fails to allow the
 hypothesis @('(p2 x y)') to be proved.  But the next binding of @('y'), to
 @('(cons a '4)'), succeeds: then the current binding alist is @('((x . a) (y
 . (cons a '4)))'), for which the hypothesis @('(p2 x y)') rewrites to true
 using the rewrite rule @('p2-instance').</p>")

(defxdoc bind-free-examples
  :parents (bind-free)
  :short "Examples pertaining to @(tsee bind-free) hypotheses"
  :long "<p>See @(see bind-free) for a basic discussion of the use of
 @('bind-free') to control rewriting.</p>

 <p>Note that the examples below all illustrate the common case in which a
 @('bind-free') hypothesis generates a binding alist.  See @(see bind-free), in
 particular the final section, for a discussion of the case that instead a list
 of binding alists is generated.</p>

 <p>We give examples of the use of @(tsee bind-free) hypotheses from the
 perspective of a user interested in reasoning about arithmetic, but it should
 be clear that @(tsee bind-free) can be used for many other purposes also.</p>

 <p>EXAMPLE 1: Cancel a common factor.</p>

 @({
  (defun bind-divisor (a b)

  ; If a and b are polynomials with a common factor c, we return a
  ; binding for x.  We could imagine writing get-factor to compute the
  ; gcd, or simply to return a single non-invertible factor.

    (let ((c (get-factor a b)))
      (and c (list (cons 'x c)))))

  (defthm cancel-factor
    ;; We use case-split here to ensure that, once we have selected
    ;; a binding for x, the rest of the hypotheses will be relieved.
    (implies (and (acl2-numberp a)
                  (acl2-numberp b)
                  (bind-free (bind-divisor a b) (x))
                  (case-split (not (equal x 0)))
                  (case-split (acl2-numberp x)))
             (iff (equal a b)
                  (equal (/ a x) (/ b x)))))
 })

 <p>EXAMPLE 2: Pull integer summand out of floor.  Note: This example has an
 <i>extended</i> @(tsee bind-free) hypothesis, which uses the term
 @('(find-int-in-sum sum mfc state)').</p>

 @({
  (defun fl (x)
    ;; This function is defined, and used, in the IHS books.
    (floor x 1))

  (defun int-binding (term mfc state)
    ;; The call to mfc-ts returns the encoded type of term.
    ;; Thus, we are asking if term is known by type reasoning to
    ;; be an integer.
    (declare (xargs :stobjs (state) :mode :program))
    (if (ts-subsetp (mfc-ts term mfc state)
                    *ts-integer*)
        (list (cons 'int term))
      nil))

  (defun find-int-in-sum (sum mfc state)
    (declare (xargs :stobjs (state) :mode :program))
    (if (and (nvariablep sum)
             (not (fquotep sum))
             (eq (ffn-symb sum) 'binary-+))
        (or (int-binding (fargn sum 1) mfc state)
            (find-int-in-sum (fargn sum 2) mfc state))
      (int-binding sum mfc state)))

  ; Some additional work is required to prove the following.  So for
  ; purposes of illustration, we wrap skip-proofs around the defthm.

  (skip-proofs
   (defthm cancel-fl-int
    ;; The use of case-split is probably not needed, since we should
    ;; know that int is an integer by the way we selected it.  But this
    ;; is safer.
     (implies (and (acl2-numberp sum)
                   (bind-free (find-int-in-sum sum mfc state) (int))
                   (case-split (integerp int)))
              (equal (fl sum)
                     (+ int (fl (- sum int)))))
     :rule-classes ((:rewrite :match-free :all)))
  )

  ; Arithmetic libraries will have this sort of lemma.
  (defthm hack (equal (+ (- x) x y) (fix y)))

  (in-theory (disable fl))

  (thm (implies (and (integerp x) (acl2-numberp y))
                (equal (fl (+ x y)) (+ x (fl y)))))
 })

 <p>EXAMPLE 3: Simplify terms such as (equal (+ a (* a b)) 0)</p>

 @({
  (defun factors (product)
    ;; We return a list of all the factors of product.  We do not
    ;; require that product actually be a product.
    (if (eq (fn-symb product) 'BINARY-*)
        (cons (fargn product 1)
              (factors (fargn product 2)))
      (list product)))

  (defun make-product (factors)
    ;; Factors is assumed to be a list of ACL2 terms.  We return an
    ;; ACL2 term which is the product of all the elements of the
    ;; list factors.
    (cond ((atom factors)
           ''1)
          ((null (cdr factors))
           (car factors))
          ((null (cddr factors))
           (list 'BINARY-* (car factors) (cadr factors)))
          (t
           (list 'BINARY-* (car factors) (make-product (cdr factors))))))

  (defun quotient (common-factors sum)
    ;; Common-factors is a list of ACL2 terms.   Sum is an ACL2 term each
    ;; of whose addends have common-factors as factors.  We return
    ;; (/ sum (make-product common-factors)).
    (if (eq (fn-symb sum) 'BINARY-+)
        (let ((first (make-product (set-difference-equal (factors (fargn sum 1))
                                                         common-factors))))
          (list 'BINARY-+ first (quotient common-factors (fargn sum 2))))
      (make-product (set-difference-equal (factors sum)
                                          common-factors))))

  (defun intersection-equal (x y)
    (cond ((endp x)
           nil)
          ((member-equal (car x) y)
           (cons (car x) (intersection-equal (cdr x) y)))
          (t
           (intersection-equal (cdr x) y))))

  (defun common-factors (factors sum)
    ;; Factors is a list of the factors common to all of the addends
    ;; examined so far.  On entry, factors is a list of the factors in
    ;; the first addend of the original sum, and sum is the rest of the
    ;; addends.  We sweep through sum, trying to find a set of factors
    ;; common to all the addends of sum.
    (declare (xargs :measure (acl2-count sum)))
    (cond ((null factors)
           nil)
          ((eq (fn-symb sum) 'BINARY-+)
           (common-factors (intersection-equal factors (factors (fargn sum 1)))
                           (fargn sum 2)))
          (t
           (intersection-equal factors (factors sum)))))

  (defun simplify-terms-such-as-a+ab-rel-0-fn (sum)
    ;; If we can find a set of factors common to all the addends of sum,
    ;; we return an alist binding common to the product of these common
    ;; factors and binding quotient to (/ sum common).
    (if (eq (fn-symb sum) 'BINARY-+)
        (let ((common-factors (common-factors (factors (fargn sum 1))
                                              (fargn sum 2))))
          (if common-factors
              (let ((common (make-product common-factors))
                    (quotient (quotient common-factors sum)))
                (list (cons 'common common)
                      (cons 'quotient quotient)))
            nil))
      nil))

  (defthm simplify-terms-such-as-a+ab-=-0
    (implies (and (bind-free
                   (simplify-terms-such-as-a+ab-rel-0-fn sum)
                   (common quotient))
                  (case-split (acl2-numberp common))
                  (case-split (acl2-numberp quotient))
                  (case-split (equal sum
                                     (* common quotient))))
             (equal (equal sum 0)
                    (or (equal common 0)
                        (equal quotient 0)))))

  (thm (equal (equal (+ u (* u v)) 0)
        (or (equal u 0) (equal v -1))))
 })")

(defxdoc bitp
  :parents (numbers acl2-built-ins)
  :short "A recognizer for the set of bits, {0,1}"
  :long "<p>@('Bitp') returns @('t') if and only its argument is @('0') or
 @('1'), and @('nil') otherwise.</p>

 <p>Note that this is a predicate form of the @(see type-spec) declaration
 @('(TYPE BIT b)').</p>

 @(def bitp)")

(defxdoc book-compiled-file
  :parents (books-reference)
  :short "Creating and loading of compiled and expansion files for @(see books)"
  :long "<p>An effect of @(see compilation) is to speed up the execution of the
 functions defined in a book.  Compilation can also remove tail recursion, thus
 avoiding stack overflows.  The presence of compiled code for the functions in
 the book should not otherwise affect the performance of ACL2.  See @(see
 guard) for a discussion; also see @(see compilation).</p>

 <p>By default, the @(tsee certify-book) command compiles the book that it
 certifies.  see @(see certify-book) for how to control this behavior.</p>

 <p>By default, the @(tsee include-book) command loads the compiled file for
 the book.  The details of how this loading works are subtle, and do not need
 to be understood by most users.  The ACL2 source code contains an ``Essay on
 Hash Table Support for Compilation'' that explains such details for those
 interested.  All that users should generally need to know about this is that
 the compiled file is always the result of compiling a so-called ``expansion
 file'', which contains certain additional code besides the book itself.  The
 relevance to users of the expansion file is that it can be loaded if the
 compiled file is missing (except when @(':load-compiled-file t') is specified
 by the @(tsee include-book) form), and its existence is required in order for
 @(tsee include-book) to create a book's compiled file, as described below.</p>

 <p>Most users can skip the remainder of this documentation topic, which
 addresses the uncommon activity of using @(tsee include-book) to compile
 books.</p>

 <p>@('Include-book') can be made to compile a book by supplying its keyword
 argument @(':load-compiled-file') the value @(':comp').  However, a compiled
 file can only be produced if there is already an <i>expansion file</i> that is
 at least as recent as the book's @(see certificate).  Such a file, whose name
 happens to be the result of concatenating the string @('"@expansion.lsp"')
 to the book's filename after removing the @('".lisp"') suffix, is created by
 @(tsee certify-book) when state global variable @(''save-expansion-file') has
 a non-@('nil') value.  That will be the case if ACL2 started up when
 environment variable @('ACL2_SAVE_EXPANSION') was @('t') (or any value that is
 not the empty string and whose @(tsee string-upcase) is not @('"NIL"')),
 until the time (if any) that @(''save-expansion-file') is assigned a different
 value by the user.  In most respects, the @(':comp') setting is treated
 exactly the same as @(':warn'); but after all events in the book are
 processed, the expansion file is compiled if a compiled file was not loaded,
 after which the resulting compiled file is loaded.</p>

 <p>One can thus, for example, compile books for several different host Lisps
 &mdash; useful when installing ACL2 executables at the same site that are
 built on different host Lisps.  A convenient way to do this in an environment
 that provides Gnu `make' is to certify the community books using the shell
 command ``@('make regression')'' in the @('acl2-sources/') directory, after
 setting environment variable @('ACL2_SAVE_EXPANSION') to @('t'), and then
 moving to the @('books') directory and executing the appropriate `make'
 commands to compile the books (targets @('fasl'), @('o'), and so on, according
 to the compiled file extension for the host Lisp).</p>

 <p>We conclude by saying more about the @(':load-compiled-file') argument of
 @(tsee include-book).  We assume that @(see state) global
 @(''compiler-enabled') has a non-@('nil') value; otherwise
 @(':load-compiled-file') is always treated as @('nil').</p>

 <p>We do not consider raw mode below (see @(see set-raw-mode)), which presents
 a special case: ACL2 will attempt to load the book itself whenever it would
 otherwise load the expansion or compiled file, but cannot (either because the
 @(':load-compiled-file') argument is @('nil'), or for each of the expansion
 and compiled files, either it does not exist or it is out of date with respect
 to the @('.cert') file).</p>

 <p>The @(':load-compiled-file') argument is not recursive: calls of
 @('include-book') that are inside the book supplied to @('include-book') use
 their own @(':load-compiled-file') arguments.  However, those subsidiary
 @('include-book') calls can nevertheless be sensitive to the
 @(':load-compiled-file') arguments of enclosing @('include-book') calls, as
 follows.  If @(':load-compiled-file') has value @('t'), then every subsidiary
 @('include-book') is required to load a compiled file.  Moreover, if a book's
 compiled file or expansion file is loaded in raw Lisp, then an attempt will be
 made to load the compiled file or expansion file for any @(tsee include-book)
 form encountered during that load.  If that attempt fails, then that load
 immediately aborts, as does its parent load, and so on up the chain.  If, when
 going up the chain, an @(tsee include-book) is aborted for which keyword
 argument @(':load-compiled-file') has value @('t'), then an error occurs.</p>

 <p>When loading a book's compiled file or expansion file, @('FILE'), it is
 possible to encounter an @(tsee include-book) form for a book that has no
 suitable compiled file or expansion file.  In that case, the load of @('FILE')
 is aborted at that point.  Similarly, the load of @('FILE') is aborted in the
 case that this @('include-book') form has a suitable compiled file or
 expansion file whose load is itself aborted.  Thus, whenever any
 @('include-book') aborts, so do all of its parent @('include-book')s, up the
 chain.  Such an abort causes an error when the @('include-book') form
 specifies a @(':load-compiled-file') value of @('t').</p>")

(defxdoc book-contents
  :parents (books-tour)
  :short "Restrictions on the forms inside @(see books)"
  :long "@({
  Example Book:

  ; This book defines my app function and the theorem that it is
  ; associative.  One irrelevant help lemma is proved first but
  ; it is local and so not seen by include-book.  I depend on the
  ; inferior book "weird-list-primitives" from which I get
  ; definitions of hd and tl.

  (in-package "MY-PKG")

  (include-book "weird-list-primitives")

  (defun app (x y) (if (consp x) (cons (hd x) (app (tl x) y)) y))

  (local
   (defthm help-lemma
     (implies (true-listp x) (equal (app x nil) x))))

  (defthm app-is-associative
    (equal (app (app a b) c) (app a (app b c))))
 })

 <p>The first form in a book must be @('(in-package "pkg")') where
 @('"pkg"') is some package name known to ACL2 whenever the book is
 certified.  The rest of the forms in a book are embedded event forms, i.e.,
 @(tsee defun)s, @(tsee defthm)s, etc., some of which may be marked @(tsee
 local).  See @(see embedded-event-form).  The usual Common Lisp commenting
 conventions are provided.  Note that since a book consists of embedded event
 forms, we can talk about the ``@(tsee local)'' and ``non-local'' @(see events)
 of a book.</p>

 <p>Because @(tsee in-package) is not an embedded event form, the only @(tsee
 in-package) in a book is the initial one.  Because @(tsee defpkg) is not an
 embedded event form, a book can never contain a @(tsee defpkg) form.  Because
 @(tsee include-book) is an embedded event form, @(see books) may contain
 references to other @(see books).  This makes @(see books) structured
 objects.</p>

 <p>When the forms in a book are read from the file, they are read with @(tsee
 current-package) set to the package named in the @(tsee in-package) form at
 the top of the file.  The effect of this is that all symbols are @(see
 intern)ed in that package, except those whose packages are given explicitly
 with the ``::'' notation.  For example, if a book begins with @('(in-package
 "ACL2-X")') and then contains the form</p>

 @({
    (defun fn (x)
      (acl2::list 'car x))
 })

 <p>then @(tsee defun), @('fn'), @('x'), and @(tsee car) are all @(see
 intern)ed in the @('"ACL2-X"') package.  I.e., it is as though the following
 form were read instead:</p>

 @({
    (acl2-x::defun acl2-x::fn (acl2-x::x)
        (acl2::list 'acl2-x::car acl2-x::x)).
 })

 <p>Of course, @('acl2-x::defun') would be the same symbol as @('acl2::defun')
 if the @('"ACL2-X"') package imported @('acl2::defun').</p>

 <p>If each book has its own unique package name and all the names defined
 within the book are in that package, then name clashes between @(see books)
 are completely avoided.  This permits the construction of useful logical @(see
 world)s by the successive inclusion of many @(see books).  Although it is
 often too much trouble to manage several packages, their judicious use is a
 way to minimize name clashes.  Often, a better way is to use @('local'); see
 @(see local).</p>

 <p>How does @(tsee include-book) know the definitions of the packages used in
 a book, since @(tsee defpkg)s cannot be among the forms?  More generally, how
 do we know that the forms in a book will be admissible in the host logical
 @(see world) of an @(tsee include-book)?  See @(see certificate) for answers
 to these questions.</p>")

(defxdoc book-example
  :parents (books-tour)
  :short "How to create, certify, and use a simple book"
  :long "<p>Suppose you have developed a sequence of admissible @(see events)
 which you want to turn into a book.  We call this ``publishing'' the book.
 This note explains how to do that.</p>

 <p>A key idea of @(see books) is that they are ``incremental'' in the sense
 that when you include a book in a host logical @(see world), the @(see world)
 is incrementally extended by the results established in that book.  This is
 allowed only if every name defined by the incoming book is either new or is
 already identically defined.  See @(see redundant-events).  This is exactly
 the same problem faced by a programmer who wishes to provide a utility to
 other people: how can he make sure he doesn't create name conflicts?  The
 solution, in Common Lisp, is also the same: use packages.  While @(see books)
 and packages have a very tenuous formal connection (every book must start with
 an @(tsee in-package)), the creation of a book is intimately concerned with
 the package issue.  Having motivated what would otherwise appear as an
 unnecessary fascination with packages below, we now proceed with a description
 of how to publish a book.</p>

 <p>Just to be concrete, let's suppose you have already gotten ACL2 to accept
 the following sequence of @(see command)s, starting in the ACL2 initial @(see
 state).</p>

 @({
     (defpkg "ACL2-MY-BOOK"
             (union-eq *common-lisp-symbols-from-main-lisp-package*
                       *acl2-exports*))
     (in-package "ACL2-MY-BOOK")
     (defun app (x y)
       (if (consp x) (cons (car x) (app (cdr x) y)) y))
     (defun rev (x)
       (if (consp x) (app (rev (cdr x)) (list (car x))) nil))
     (defthm rev-app-hack
       (equal (rev (app a (list x))) (cons x (rev a))))
     (defthm rev-rev
       (implies (acl2::true-listp x) (equal (rev (rev x)) x)))
 })

 <p>Observe that the first form above defines a package (which imports the
 symbols defined in CLTL such as @(tsee if) and @(tsee cons) and the symbols
 used to @(see command) ACL2 such as @(tsee defun) and @(tsee defthm)).  The
 second form selects that package as the current one.  All subsequent forms are
 read into that package.  The remaining forms are just event forms: @(tsee
 defun)s and @(tsee defthm)s in this case.</p>

 <p>Typically you would have created a file with Emacs containing these forms
 and you will have submitted each of them interactively to ACL2 to confirm that
 they are all admissible.  That interactive verification should start in ACL2's
 initial @(see world) &mdash; although you might, of course, start your
 sequence of @(see events) with some @(tsee include-book)s to build a more
 elaborate @(see world).</p>

 <p>The first step towards publishing a book containing the results above is to
 create a file that starts with the @(tsee in-package) and then contains the
 rest of the forms.  Let's call that file @('"my-book.lisp"').  The name is
 unimportant, except it must end with @('".lisp"').  If there are @(see
 events) that you do not wish to be available to the user of the book &mdash;
 e.g., lemmas you proved on your way toward proving the main ones &mdash; you
 may so mark them by enclosing them in @(tsee local) forms.  See @(see local).
 Let us suppose you wish to hide @('rev-app-hack') above.  You may also add
 standard Lisp comments to the file.  The final content of
 @('"my-book.lisp"') might be:</p>

 @({
   ; This book contains my app and rev functions and the theorem
   ; that rev is its own inverse.

     (in-package "ACL2-MY-BOOK")
     (defun app (x y)
       (if (consp x) (cons (car x) (app (cdr x) y)) y))
     (defun rev (x)
       (if (consp x) (app (rev (cdr x)) (list (car x))) nil))

   ; The following hack is not exported.
     (local (defthm rev-app-hack
       (equal (rev (app a (list x))) (cons x (rev a)))))

     (defthm rev-rev
       (implies (acl2::true-listp x) (equal (rev (rev x)) x)))
 })

 <p>The file shown above <b>is</b> the book.  By the time this note is done you
 will have seen how to certify that the book is correct, how to compile it, and
 how to use it in other host @(see world)s.  Observe that the @(tsee defpkg) is
 not in the book.  It cannot be: Common Lisp compilers disagree on how to treat
 new package definitions appearing in files to be compiled.</p>

 <p>Since a book is just a source file typed by the user, ACL2 provides a
 mechanism for checking that the @(see events) are all admissible and then
 marking the file as checked.  This is called certification.  To certify
 @('"my-book.lisp"') you should first get into ACL2 with an initial @(see
 world).  Then, define the package needed by the book, by typing the following
 @(tsee defpkg) to the ACL2 @(see prompt):</p>

 @({
  ACL2 !>(defpkg "ACL2-MY-BOOK"
                 (union-eq *common-lisp-symbols-from-main-lisp-package*
                           *acl2-exports*))
 })

 <p>Then execute the @(see command):</p>

 @({
  ACL2 !>(certify-book "my-book" 1 t) ; the `t' is in fact the default
 })

 <p>Observe that you do not type the @('".lisp"') part of the file name.  For
 purposes of @(see books), the book's name is @('"my-book"') and by the time
 all is said and done, there will be several extensions in addition to the
 @('".lisp"') extension associated with it.</p>

 <p>The @('1') tells @(tsee certify-book) that you acknowledge that there is
 one command in this ``certification @(see world)'' (namely the @(tsee
 defpkg)).  To use the book, any prospective host @(see world) must be extended
 by the addition of whatever @(see command)s occurred before certification.  It
 would be a pity to certify a book in a @(see world) containing junk because
 that junk will become the ``@(see portcullis)'' guarding entrance to the book.
 The @('t') above tells @(tsee certify-book) that you wish to compile
 @('"my-book.lisp"') also (but see @(see compilation) for an exception).
 @(tsee Certify-book) makes many checks but by far the most important and
 time-consuming one is that it ``proves'' every event in the file.</p>

 <p>When @(tsee certify-book) is done it will have created two new files.  The
 first will be called @('"my-book.cert"') and contains the ``@(see
 certificate)'' attesting to the admissibility of the @(see events) in
 @('"my-book.lisp"').  The @(see certificate) contains the @(tsee defpkg) and
 any other forms necessary to construct the certification @(see world).  It
 also contains so-called @(see book-hash) values that are used to help you keep
 track of which version of @('"my-book.lisp"') was certified.</p>

 <p>The second file that may be created by @(tsee certify-book) is the compiled
 version of @('"my-book.lisp"') and will have a name that is assigned by the
 host compiler (e.g., @('"my-book.o"') in GCL, @('"my-book.fasl"') in
 SBCL).  @(tsee Certify-book) will also load this object file.  When @(tsee
 certify-book) is done, you may throw away the logical @(see world) it created,
 for example by executing the @(see command) @(':u').</p>

 <p>To use the book later in any ACL2 session, just execute the event
 @('(include-book "my-book")').  This will do the necessary @(tsee defpkg),
 load the non-@(tsee local) @(see events) in @('"my-book.lisp"') and then may
 load the compiled code for the non-local functions defined in that file.
 Checks are made to ensure that the @(see certificate) file exists and
 describes the version of @('"my-book.lisp"') that is read.  The compiled
 code is loaded if and only if it exists and has a later write date than the
 source file (but see @(see compilation) for an exception).</p>

 <p>Since @(tsee include-book) is itself an event, you may put such forms into
 other @(see books).  Thus it is possible for the inclusion of a single book to
 lead to the inclusion of many others.  The @(see book-hash) information
 maintained in @(see certificate)s helps deal with the version control problem
 of the referenced @(see books).  I.e., if this version of @('"my-book"') is
 used during the certification of @('"your-book"'), then the @(see
 certificate) for @('"your-book"') includes the book-hash for this version of
 @('"my-book"').  If a later @('(include-book "your-book")') finds a
 version of @('"my-book"') with a different book-hash, an error is signaled.
 But book-hash values are not perfect and the insecurity of the host file
 system prevents ACL2 from guaranteeing the logical soundness of an @(tsee
 include-book) event, even for a book that appears to have a valid @(see
 certificate) (they can be forged, after all).  (See @(see certificate) for
 further discussion.)</p>

 <p>This concludes the example of how to create, certify and use a book.  If
 you wish, you could now review the @(see documentation) for book-related
 topics (see @(see books)) and browse through them.  They'll probably make
 sense in this context.  Alternatively, you could continue the ``guided tour''
 through the rest of the @(see documentation) of @(see books).  See @(see
 book-name), following the pointer given at the conclusion.</p>")

(defxdoc book-hash
  :parents (books)
  :short "Assigning ``often unique'' fingerprints to @(see books)"
  :long "<p>ACL2 provides a <i>certification</i> process for recording into a
 @(see certificate) file that a book is valid.  That process records certain
 ``fingerprint'' values for the book and the books that it includes, in order
 to give some confidence in the book's validity.  We call that value the
 ``book-hash'' for the book.  By default, a book-hash is an alist that records,
 for a given book (@('.lisp') file), its file size (in bytes) and its
 write-date.</p>

 <p>You can arrange for a book-hash to be a checksum instead of an alist, which
 gives a bit greater security, as illustrated in an example provided below.
 See @(see checksum).  Nevertheless, the (default) use of book-hash alists may
 be worthwhile, in spite of the decreased security, because of faster times for
 @(tsee certify-book) and @(tsee include-book) when using book-hash alists
 instead of checksums.  If you want to use checksums, however, there are these
 two ways to do so.</p>

 <ul>

 <li>Before starting ACL2, set environment variable @('ACL2_BOOK_HASH_ALISTP')
 to @('NIL') (or @('nil'); actually it suffices that @(tsee string-upcase)
 applied to the indicated string is @('"NIL"')).  A common way to get this
 effect is to supply the argument @('ACL2_BOOK_HASH_ALISTP=NIL') with your
 @('"make"') command.</li>

 <li>After starting ACL2, set @(see state) global variable
 @('book-hash-alistp') to @('nil'), e.g.: @('(assign book-hash-alistp
 nil)').  (Set this variable to @('t') to revert to the default behavior:
 @('(assign book-hash-alistp t)').)</li>

 </ul>

 <p>The simple example below illustrates the potential weakness of book-hash
 alists (as compared to checksums), by exploiting the fact that these alists do
 not hash information in the @(see certificate) itself.  (Book-hash alists also
 ignore @(see portcullis) @(see command)s and the corresponding @('.acl2x')
 file, if any (see @(see set-write-acl2x)); but we don't exploit these facts in
 this example.)  We start with the following book, @('"foo.lisp"').</p>

 @({
 (in-package "ACL2")
 (make-event '(defun foo (x) (cons x x)))
 })

 <p>Now start ACL2 and run these commands.</p>

 @({
 (assign book-hash-alistp t) ; a no-op, by default
 (certify-book "foo")
 (read-file "foo.cert" state)
 (quit)
 })

 <p>Next, replace the contents of @('"foo.cert"') by the values in the list
 printed by the @('read-file') form above (hence, without the outer
 parentheses).  Further edit that file by twice changing @('(cons x x)') to
 @('x').  Also, update the write-date on the compiled file, e.g. with @('touch
 foo.dx64fsl'), if you want to avoid a warning.  Then submit @('(include-book
 "foo")').  We get the following contradictory behavior, without any
 warnings.</p>

 @({
 ACL2 !>(foo 3)
 (3 . 3)
 ACL2 !>(thm (equal (foo x) x))

 Q.E.D.

 Summary
 Form:  ( THM ...)
 Rules: ((:DEFINITION FOO))
 Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
 Prover steps counted:  5

 Proof succeeded.
 ACL2 !>
 })

 <p>For more information about connections between book-hash values and
 certification status, see @(see book-hash-mismatch).</p>")

(defxdoc book-hash-mismatch
  :parents (book-hash)
  :short "Deeming a book uncertified because of a @(see book-hash) mismatch"
  :long "<p>When @(tsee include-book) is invoked, the specified book may be
 considered uncertified by ACL2 because its @(see book-hash) &mdash; which by
 default is an alist specifying the book's size and write-date, but could be a
 checksum &mdash; does not match what was expected.  In that case you will
 typically see a warning such as the following, which instead will be an error
 if this occurs during certification.  In this topic, we explain how this
 warning can occur.</p>

 @({
 ACL2 Warning [Uncertified] in ( INCLUDE-BOOK "foo" ...):
 The certificate for "/Users/kaufmann/temp/foo.lisp" lists the book-
 hash of that book as ((:BOOK-LENGTH . 38) (:BOOK-WRITE-DATE . 3674050905)).
 But its book-hash is now computed to be
 ((:BOOK-LENGTH . 39) (:BOOK-WRITE-DATE . 3674050914)).
 See :DOC book-hash-mismatch.
 })

 <p>Probably the simplest way for such a mismatch to occur is if you change the
 book after certifying it, and then try to include the book.  In the example
 message displayed above, the book-hash for @('foo.lisp') stored into
 @('foo.cert') was 516310554.  But then @('foo.lisp') was edited (in this case,
 by adding a single newline character), and ACL2 complained because at
 @('include-book') time it computed a different book-hash for that book.</p>

 <p>The mismatch might occur on a book that is being included while including a
 superior book.  For example, suppose that the act of evaluating
 @('(include-book "bk1")') triggers evaluation of the event @('(include-book
 "bk2")') from @('bk1.lisp'), which similarly in turn causes evaluation of
 the event @('(include-book "bk3")') from @('bk2.lisp').  Now certify
 @('bk3.lisp'), then @('bk2.lisp'), and finally @('bk1.lisp').  So far, so
 good.  But now suppose we edit the lowest-level book, @('bk3.lisp').  We will
 likely get a warning (or error, if during book certification) such as the
 one displayed above when evaluating @('(include-book "bk1")'), complaining
 that the book-hash for @('bk3.lisp') has changed &mdash; followed by warnings
 complaining about inclusions of uncertified books by superior books.</p>

 <p>There are several ways for a book-hash in a @('.cert') file to become
 invalid, that is, to fail to match a recomputation of the book-hash when later
 including the book.  All such mismatches are due to a difference between the
 value of a book-hash at certification time and at later @('include-book')
 time; see @(see book-hash).</p>

 <p>Note that it is possible to mix alist and checksum book-hash values.  The
 key is to avoid conflicts between book-hash values stored for the same book in
 different @('.cert') files.  The following example works fine, because there
 is no such conflict: the book @('"sub"') is associated with a book-hash
 checksum in @('sub.cert'), which provides that same checksum as the book-hash
 value for @('"sub"') in @('top.cert'); and the book @('"top"') is
 associated with a book-hash alist in @('top.cert').</p>

 @({
 (certify-book "sub")
 (u)
 (assign book-hash-alistp t)
 (certify-book "top") ; contains the event (include-book "sub")
 (u)
 (include-book "top") ; no problem!
 })

 <p>However, if we instead evaluate the following forms in a fresh ACL2
 session, the last one causes an error, because a checksum serves as the
 book-hash for @('"sub"') in @('top.cert'), but at @('include-book') time the
 book-hash for @('"sub"') in @('sub.cert') is an alist, not a checksum.</p>

 @({
 (certify-book "sub")
 :u
 (certify-book "top") ; contains the event (include-book "sub")
 :u
 (assign book-hash-alistp t)
 (certify-book "sub") ; now the book-hash for sub is an alist
 :u
 ; Error: mismatch for book-hash values for "sub" in
 ;        new sub.cert and earlier top.cert.
 (include-book "top")
 })

 <p>That said, ACL2 does not care about the current value of state global
 @('book-hash-alistp') at @('include-book') time.  For example, the following
 works without error: ACL2 sees the checksum stored in @('sub.cert'), so at
 @('include-book') time it computes a checksum for the book @('"sub"'), not
 an alist, even though @(''book-hash-alistp') has value @('t').</p>

 @({
 (assign book-hash-alistp nil)
 (certify-book "foo")
 (assign book-hash-alistp t)
 (include-book "foo")
 })

 <p>We conclude by discussing a rather insidious book-hash mismatch that can
 occur when including a book using an ACL2 executable that differs from the
 executable that was used when certifying the book.  Here is an example.
 Consider a book, @('"foo.lisp"'), containing the event @('(include-book
 "tools/remove-hyps" :dir :system)').  Suppose we have ACL2 executables
 @('acl2-cksum') and @('acl2-alist'), in different ACL2 directories.  Also
 suppose that we have certified (disjoint copies of) the @(see community-books)
 with each of these ACL2 executables, where we used
 @('ACL2_BOOK_HASH_ALISTP=NIL') in our @('"make"') command with
 @('acl2-cksum') but not with @('acl2-alist').  Now suppose we certify
 @('"foo.lisp"') using @('acl2-cksum') but then, in a session with
 @('acl2-alist'), we include that same book.  Then we will see a warning
 beginning as displayed below.  It complains that the book-hash required of
 @('books/tools/remove-hyps.cert') according to @('foo.cert') &mdash; which was
 created using @('acl2-cksum') &mdash; differs from the book-hash in the
 @('.cert') file of the copy of that book that is under the directory of the
 currently running ACL2, @('acl2-alist').</p>

 @({
 ACL2 Warning [Uncertified] in ( INCLUDE-BOOK "foo" ...):  After including
 the book "/Users/smith/temp/foo.lisp":

 -- its certificate requires the book "/Users/smith/acl2/books/tools/remove-
 hyps.lisp" with certificate annotations
   ((:SKIPPED-PROOFSP) (:AXIOMSP) (:TTAGS))
 and book hash 1958615726, but we have included a version of "remove-hyps"
 with certificate annotations
   ((:SKIPPED-PROOFSP) (:AXIOMSP) (:TTAGS))
 and book-hash ((:BOOK-LENGTH . 14650) (:BOOK-WRITE-DATE . 3656629263)),
 so book recertification is probably required;
 })")

(defxdoc book-name
  :parents (books-tour)
  :short "Conventions associated with book-names"
  :long "@({
  Examples:
  "list-processing"
  "/usr/home/smith/my-arith"
 })

 <p>A <i>book-name</i> is typically a string constant that represents a file.
 (Much later below we discuss other book-names that are not strings, namely,
 @(see sysfile)s; but till then we consider only strings.)  We elaborate book
 names by concatenating the ``connected book directory'' (see @(see cbd))
 string on the left and perhaps a @('".lisp"') ``extension'' on the right.
 However, the connected book directory is not added if the book-name itself
 already represents an absolute file name.  Furthermore, @(tsee include-book)
 and @(tsee certify-book) temporarily reset the connected book directory to be
 the directory of the book being processed.  This allows @(tsee include-book)
 forms to use relative pathnames without explicit mention of the enclosing
 book's directory.</p>

 <p>You may wish to read elsewhere for details of ACL2 file name conventions
 (see @(see pathname)), for a discussion of the filename that is the result of
 the elaboration described here (see @(see full-book-name)), and for details of
 the concept of the connected book directory (see @(see cbd)).  For details of
 how @(tsee include-book) (see @(see include-book)) and @(tsee certify-book)
 (see @(see certify-book)) use these concepts, see below.</p>

 <p>Often a book-name is simply the familiar name of the file.  (See @(see
 full-book-name) for discussion of the notions of ``directory string,''
 ``familiar name,'' and ``extension''.  These concepts are not on the guided
 tour through @(see books) and you should read them separately.)  However, it
 is permitted for a book-name to include a directory or part of a directory
 name.  Book-names often do not include the extension, since ACL2 must
 routinely tack several different extensions onto the name during @(tsee
 include-book).  For example, @(tsee include-book) uses the @('".lisp"'),
 @('".cert"') and possibly a compiled file extension (like @('".fasl"')) of
 the book-name.</p>

 <p>A book-name is elaborated into a @(see full-book-name) by @(tsee
 include-book) and @(tsee certify-book).  This elaboration is sensitive to the
 ``connected book directory.'' The connected book directory is an absolute
 filename string (see @(see pathname)) that is part of the ACL2 @(tsee
 state).  (You may wish to see @(see cbd) and to see @(see set-cbd) &mdash;
 note that these are not on the guided tour).  If a book-name is an absolute
 filename string, ACL2 elaborates it simply by appending the desired extension
 to the right.  If a book-name is a relative filename string, ACL2 appends the
 connected book directory on the left and the desired extension on the
 right.</p>

 <p>Note that it is possible that the book-name includes some partial
 specification of the directory.  For example, if the connected book directory
 is @('"/usr/home/smith/"') then the book-name @('"project/task-1/arith"')
 is a book-name that will be elaborated to</p>

 @({
  "/usr/home/smith/project/task-1/arith.lisp".
 })

 <p>Observe that while the @(see events) in this @('"arith"') book are being
 processed the connected book directory will temporarily be set to</p>

 @({
  "/usr/home/smith/project/task-1/".
 })

 <p>Thus, if the book requires other @(see books), e.g.,</p>

 @({
  (include-book "naturals")
 })

 <p>then it is not necessary to specify the directory on which they reside
 provided that directory is the same as the superior book.</p>

 <p>This inheritance of the connected book directory and its use to elaborate
 the names of inferior @(see books) makes it possible to move @(see books) and
 their inferiors to new directories, provided they maintain the same relative
 relationship.  It is even possible to move with ease whole collections of
 @(see books) to different filesystems that use a different operating system
 than the one under which the original certification was performed.</p>

 <p>The @('".cert"') extension of a book, if it exists, is presumed to
 contain the most recent @(see certificate) for the book.  See @(see
 certificate) (or, if you are on the guided tour, wait until the tour gets
 there).</p>

 <p>Finally we mention another kind of book-name: a @(see sysfile), which is a
 pair that associates a keyword with a relative pathname.  This kind of
 book-name is used by the implementation, for example in @(see certificate)
 files, but is rarely visible to users.  If you run across a sysfile and want
 to understand more about it, see @(see sysfile).</p>

 <p>See @(see book-contents) to continue the guided tour.</p>")

(defxdoc bookdata
  :parents (books)
  :short "Write small files with meta-data about certified @(see books)"
  :long "<p>ACL2 provides a primitive capability for writing out a file of
 metadata associated with a book.  This information might be useful, for
 example, in building a database that allows you to search for name conflicts.
 See @(see community-books) directory @('books/tools/book-conflicts/') for an
 application of this capability by Dave Greve.  If you use this capability and
 have ideas for enhancing it, please feel free to send them to the ACL2
 developers.</p>

 <p>If the book has the name @('BK'), then the output file is named
 @('BK__bookdata.out').  That file is generated in the same directory as
 @('BK'), by certifying @('BK') when @(see state) global @(''write-bookdata')
 has a non-@('nil') value, for example as follows.</p>

 @({
  (assign write-bookdata t)
  (certify-book "BK" ...)
 })

 <p>Alternatively, one may set environment variable @('ACL2_WRITE_BOOKDATA') to
 any non-empty value to cause @('BK__bookdata.out') to be written, with one
 exception, namely: when the value of state global @('write-bookdata') is
 @(':never').</p>

 <p>The resulting file will contain a single form of the following shape,
 although not necessarily in the following order, according to the description
 that follows below.</p>

 @({
  ("...BK.lisp"
   :PKGS          pkgs-val
   :BOOKS         book-val
   :PORT-BOOKS    port-book-val
   :CONSTS        consts-val
   :PORT-CONSTS   port-consts-val
   :FNS           fns-val
   :PORT-FNS      port-fns-val
   :LABELS        labels-val
   :PORT-LABELS   port-labels-val
   :MACROS        macros-val
   :PORT-MACROS   port-macros-val
   :STOBJS        stobjs-val
   :PORT-STOBJS   port-stobjs-val
   :THEORIES      theories-val
   :PORT-THEORIES port-theories-val
   :THMS          thms-val
   :PORT-THMS     port-thms-val
 )})

 <p>The first entry in the form will always be the @(see full-book-name) of the
 certified book, @('BK'), possibly in @(see sysfile) format.</p>

 <p>Subsequent values in the form are based on @(see events) introduced by
 including @('BK').  For various values of @('xxx') as described below,
 @('port-')<i>xxx</i>@('-val') is a list of values corresponding to @(see
 events) introduced in the certification @(see world) for @('BK') (see @(see
 portcullis)), and <i>xxx</i>@('-val') is a list of values corresponding to
 @(see events) introduced non-@(tsee local)ly by @('BK').  These lists include
 only ``top-level'' events, not those that are introduced by a book included
 either in @('BK') or its certification world.</p>

 <p>@('Pkgs-val') is a list of names of packages introduced in the
 certification world (at the top level, not in an included book).  Note that no
 packages are introduced in a book itself, so no distinction is made between
 @('pkgs-val') and @('port-pkgs-val').  Both @('port-book-val') and
 @('book-val') are lists of @(see full-book-name)s of included books.  The
 values associated with the other keywords are, themselves, association
 lists (see @(see alistp)) such that each key is a package name, which is
 associated with a list of @(see symbol-name)s for symbols in that package that
 are introduced for that keyword.  For example, @('fns-val') may be the
 alist</p>

 @({
  (("ACL2" "F1" "F2")
   ("MY-PKG" "G1" "G2"))
 })

 <p>if the function symbols introduced in the book are @('F1') and @('F2') in
 the @('"ACL2"') package, as well as @('G1') and @('G2') in the
 @('"MY-PKG"') package.</p>

 <p>We next explain what kinds of symbols are introduced for each keyword
 @(':xxx').  Each such symbol would be associated with either the keyword
 @(':port-xxx') or the keyword @(':xxx') depending respectively on whether the
 symbol is introduced at the top level of the certification world for @('BK')
 or @('BK') itself.</p>

 <dl>

 <dt>@(':CONSTS')</dt>

 <dd>constant symbol introduced by @('defconst')</dd>

 <dt>@(':FNS')</dt>

 <dd>function symbol: introduced by @('defun'), @('defuns'), or @('defchoose'); or
 constrained (by an @(tsee encapsulate) event)</dd>

 <dt>@(':LABELS')</dt>

 <dd>symbol introduced by @('deflabel')</dd>

 <dt>@(':MACROS')</dt>

 <dd>macro name introduced by @('defmacro')</dd>

 <dt>@(':STOBJS')</dt>

 <dd>@('stobj') name introduced by @('defstobj') or @('defabsstobj')</dd>

 <dt>@(':THEORIES')</dt>

 <dd>theory name introduced by @('deftheory')</dd>

 <dt>@(':THMS')</dt>

 <dd>theorem name, which may be introduced by @('defthm') or a macro call
 expanding to a call of @('defthm'), such as see @(see defequiv) or
 @('defaxiom'); but may be introduced by @(tsee defpkg), for example, with
 name @('"MYPKG-PACKAGE"') if the package name is @('"MYPKG"')</dd>

 </dl>

 <p>Our hope is that people in the ACL2 community will generate and use this
 data to improve the ACL2 @(see community-books).  Here is an example
 illustrating how to generate bookdata files for those books as a byproduct of
 a regression run.  Below, we write @('{DIR}') as an abbreviation for the ACL2
 sources directory, and assume that this command is run from that directory.
 Of course, you may wish to use @('make') options like @('-j 8') and @('make')
 variable settings like @('ACL2={DIR}/my-saved_acl2'); see @(see
 books-certification) for details.</p>

 @({
   make regression-fresh \
   ACL2_CUSTOMIZATION={DIR}/acl2-customization-files/bookdata.lisp
 })")

(defxdoc books
  :parents (top)
  :short "<i>Books</i> are files of ACL2 @(see events)&mdash;they are the main
way to split up large ACL2 developments into separate modules."
  :long "<p>This @(see documentation) topic is about ACL2 <a
 href='https://en.wikipedia.org/wiki/Source_code'>source code</a> files.
 However, there are also books published about ACL2 and its applications; see
 @(see pubs::pubs-books).</p>

 <p>You will almost surely want to organize your own ACL2 work into books.
 They facilitate reuse, allow you to reload proofs more quickly, allow you to
 rebuild parts of your proof in parallel, and so forth.  You will also want to
 be aware of the many <i>community books</i>, which provide useful tools and
 lemmas to build upon.  See @(see community-books) for more information,
 including how to contribute.</p>

 <h3>Introduction</h3>

 <p>A <b>book</b> is a file of ACL2 forms.  Books are prepared entirely by the
 user of the system, i.e., they are <i>source files</i> not <i>object
 files</i>.  Some of the forms in a book are marked @(tsee local) and the
 others are considered ``non-local.''</p>

 <p>@(tsee Include-book) lets you load a book into any ACL2 @(see world).  A
 successful @('include-book') extends the logic of the host @(see world) by
 adding just the non-local @(see events) in the book.  Ordinarily, you might
 include a variety of books to load all of their definitions and rules.</p>

 <p>Successful book inclusion is consistency preserving, provided that the book
 itself is consistent, as discussed later.  However, @(tsee include-book)
 assumes the @(see events) in a book are valid, so if you include a book that
 contains an inconsistency (e.g., an inadmissible definition) then the
 resulting theory is inconsistent!</p>

 <p>@(tsee Certify-book) lets you <i>certify</i> a book to guarantee that its
 successful inclusion is consistency preserving.  During certification, both
 the @(tsee local) and non-local forms are processed.  This lets you mark as
 @(tsee local) any @(see events) you need for certification, but that you want
 to hide from users of the book&mdash;e.g., the hacks, crocks, and kludges on
 the way to a good set of @(see rewrite) rules.</p>

 <p>Certification can also <see topic='@(url compilation)'>compile</see> a book
 to speed up the execution of the functions defined within it.  The desire to
 compile books is largely responsible for the restrictions we put on the forms
 allowed in books.</p>

 <p>Extensive @(see documentation) is available on the various aspects of
 books.  We recommend that you read it all before using books.  It has been
 written so as to make sense when read in a certain linear sequence, called the
 ``guided tour'', though in general you may browse through it randomly.  If you
 are on the guided tour, you should next read @(see book-example).</p>")

(defxdoc books-certification
  :parents (community-books)
  :short "Instructions for certifying the ACL2 @(see community-books)."
  :long "<p>The <see topic='@(url community-books)'>Community Books</see>
 provides a @('make') system, which is recommended for certifying a specified
 subset of those books from the @('books/') directory of your ACL2 distribution.
 Alternate instructions are however available for certifying from the top-level
 directory (see @(see books-certification-alt)).</p>

 <p>Below are instructions for certifying various sets of books.  They all have
 the following form in common.  Note: If there is a suitable @('"acl2"')
 executable on your Unix @('PATH') &mdash; for example, if the @('bin')
 subdirectory of the main ACL2 directory is on your @('PATH'), so that
 @('bin/acl2') may be your executable &mdash; then you can omit
 @('"ACL2=..."') below.</p>

 @({
 cd /path/to/acl2-sources/books
 make ACL2=/path/to/acl2-sources/saved_acl2 ...
 })

 <p>For example, the section ``A Full Build'', below, says to do the following
 if you would like to make a change to the @(see community-books) (where the
 @('-j') argument is optional).</p>

 @({
     $ cd /path/to/acl2-sources/books
     $ make ACL2=/path/to/acl2-sources/saved_acl2 -j 2 all
 })

 <p>Success is indicated by a Linux exit status of 0.  Equivalently, there
 should be no failures in the log.  Failures may be found by searching for
 @('**'); for example, if output is redirected to a log file
 @('make-regression.log'), then the following should provide no output.</p>

 @({
 fgrep -a '**' make-regression.log
 })

 <p>Unusual books that create output in the log file should not produce the
 string @('**') except upon failure.</p>

 <p>By default, @('make') commands for certifying books take advantage of files
 @('*@useless-runes.lsp').  See @(see useless-runes).</p>

 <h3>Prerequisites</h3>

 <p>We assume that you have already installed ACL2 as per the
 @(see installation-instructions).  In particular, the @(see community-books)
 should be present as the @('books/') subdirectory of your ACL2
 distribution.</p>

 <p>We assume you know the path to your ACL2 executable.  Typically this is a
 script named @('saved_acl2') in your @('acl2-sources') directory.</p>

 <p>The instructions below are suitable for ACL2 and all of its experimental
 extensions, e.g., ACL2(p) and ACL2(r).</p>

 <p>It may be preferable to avoid being logged in as root, since developers do
 not test as root and at least one community book
 (@('books/oslib/tests/copy.lisp')) has failed to certify when logged in as
 root.</p>

 <h3>A Basic Build</h3>

 <p>The default @('make') target in @('books/GNUmakefile'), called
 @('basic'), is quite fast &mdash; it excludes many books and certifies only
 the directories listed below, which tend to be widely used.  <b>WARNING</b>:
 This basic build is insufficient for validating
 changes that will go into the @(see community-books); for that, see
 @(see how-to-contribute).</p>

 <ul>
 <li>arithmetic</li>
 <li>arithmetic-3</li>
 <li>arithmetic-5</li>
 <li>@(see ihs)</li>
 <li>misc</li>
 <li>tools (mostly)</li>
 <li>@(see std) (mostly)</li>
 <li>@(see xdoc) (in part)</li>
 <li>data-structures</li>
 <li>apply</li>
 </ul>

 <p>To certify these books, you should be able to run @('make') as follows.  The
 @('-j 2') part of this command is suitable for a computer with two cores.  If
 you have, e.g., a quad-core computer, you should probably use @('-j 4')
 instead, and so on.</p>

 @({
     $ cd /path/to/acl2-sources/books
     $ make ACL2=/path/to/acl2-sources/saved_acl2 -j 2 basic
 })

 <p>If you configure your @('PATH') so that you can launch ACL2 by typing
 @('acl2'), then you may omit the @('ACL2=...') part.</p>


 <h3>Certifying Additional Books</h3>

 <p>We expect that most ACL2 users will want to certify at least the @('basic')
 books described above.  But what if you also need other books?  One option is
 to do a full build (see below).  But it is usually <b>much faster</b> to simply
 tell @('make') to build the books you actually want to use.</p>

 <p>There are @('make') targets corresponding to most directory names.  For
 instance, to build the books under @('coi') and @('rtl') and @('cgen'), you can
 run:</p>

 @({
     $ cd /path/to/acl2-sources/books
     $ make ACL2=/path/to/acl2-sources/saved_acl2 coi rtl cgen -j 2
 })

 <p>For finer grained control, you can name individual books.  This works
 particularly well for libraries that have @('top') books.  For instance, if you
 want the @('rtl/rel9') library, you could run:</p>

 @({
     $ cd /path/to/acl2-sources/books
     $ make ACL2=/path/to/acl2-sources/saved_acl2 rtl/rel9/lib/top.cert -j 2
 })


 <h3>Books that Require ACL2 Extensions</h3>

 <p>Some books require experimental extensions to ACL2, such as ACL2(p) (see
 @(see parallelism)) or ACL2(r) (see @(see real)).  Other books require certain
 additional software.</p>

 <p>The build system will automatically determine which kind of ACL2 you are
 running (ACL2, ACL2(p), or ACL2(r)) and, based on this, may prevent
 incompatible books from being certified.  The output of @('make') should
 explain which books are being excluded and why.</p>

 <p>These kinds of book requirements are controlled by special @(see
 build::cert_param) comments.</p>


 <h3>Books that Require Quicklisp</h3>

 <p>Some books, especially @(see interfacing-tools) like @(see oslib) and the
 ACL2 @(see bridge), require certain Common Lisp libraries.</p>

 <p>These libraries are now bundled with ACL2 via @(see quicklisp), so you
 should not need to download anything extra to use them.  They are enabled by
 default for all host Lisps except GCL, but you can avoid books that depend on
 Quicklisp libraries by setting @('USE_QUICKLISP=0') in your
 @('make') command.</p>

 <p>Using Quicklisp should definitely work if the host Lisp is CCL or SBCL.
 (Note however that certification of @(see books) that use
 Quicklisp may require @('openssl') to be installed if it is not already
 on your system.)
 There is some chance it will work with Allegro CL, LispWorks, and CMUCL.  It
 will almost certainly <b>not</b> work for GCL (at least as of 2018).</p>


 <h3>Books that Require Additional Software</h3>

 <p>Some other books based on @(see satlink) and @(see gl) require a SAT solver,
 typically Glucose, to be installed; see @(see satlink::sat-solver-options) for
 installation options.  The build system should automatically determine if
 Glucose is installed on your system, and will avoid trying to certify these
 books unless Glucose is present.</p>


 <h3>Building the manual</h3>

 <p>If you just want to get a copy of the ACL2+Books manual for local viewing,
 you probably <b>don't need to build it yourself</b> because you can just <a
 href='download/'>download</a> a copy.  If for some reason you do want to build
 the manual yourself, you should be able to do so as follows.</p>

 @({
     $ cd /path/to/acl2-sources/books
     $ make manual -j 4
 })

 <p>Building the manual should work on at least CCL and SBCL on Linux and Mac OS
 X.  It <b>may not work</b> for some other OS/Lisp combinations.  In particular,
 building the manual requires some features from @(see oslib) and @(see
 quicklisp) that may not be available on some other Lisps.</p>

 <p>The resulting web-based manual may be found in:</p>

 @({
     acl2-sources/books/doc/manual/index.html
 })

 <p>See also @(see acl2::acl2-doc) for details about how to build your own
 Emacs-based manual, and @(see xdoc::save) for general information about how to
 build and distribute custom XDOC manuals, e.g., manuals that additionally
 include your own unreleased books.</p>


 <h3>A Full Build</h3>

 <p>Building all of the books can take hours and is <b>usually unnecessary</b>.
 That said, it is easy to do: just run @('make all'), for example as follows.
 (But as noted above, you may omit @('"ACL2=..."') if a suitable executable
 named @('acl2') is on your Unix @('PATH'), such as @('bin/acl2').)</p>

 @({
     $ cd /path/to/acl2-sources/books
     $ make ACL2=/path/to/acl2-sources/saved_acl2 -j 2 all
 })

 <p>This includes a few books that are quite slow to certify.  You can
 exclude those by replacing ``@('all')'' by ``@('regression')'' in the
 command above.</p>


 <h3>Cleaning Up</h3>

 <p>If you want to delete generated files, you can run @('make clean') to remove
 certificates, compiled files, and build logs.</p>

 <p>If you just want to remove the files in a particular subdirectory (and its
 subdirectories), you can go into that directory and then run the
 @('build/clean.pl') script.  This will delete, starting from your current
 directory, recursively, all certificates, logs, compiled files, etc.</p>

 <p>Note that @('make clean') doesn't remove some files, e.g., @(see xdoc)
 manuals.  To remove everything, try @('make moreclean').</p>


 <h3>Debugging Failed Certifications</h3>

 <p>If a book fails to certify, you may want to try certifying it in an
 interactive session.  The most reliable way to do this is to replicate the
 environment and commands that the build system used.  This information can be
 found at the top of the @('[bookname].cert.out') file.  For instance:</p>

 @({
     ;; foo.cert.out
     -*- Mode: auto-revert -*-
     ...
     Environment variables:
     ACL2_CUSTOMIZATION=NONE                 ;; <-- first configure your
     ACL2_SYSTEM_BOOKS=/path/to/acl2/books   ;;     environment to match
     ACL2=/path/to/saved_acl2                ;;     these settings
     ...
     Temp lisp file:
     (acl2::value :q)                 ;; <--- then submit these commands to
     (acl2::in-package "ACL2")      ;;      $ACL2 to debug the failure
     ...                              ;;      interactively
     --- End temp lisp file ---
 })

 <p>Some other notes/tips:</p>

 <ul>

 <li>Make sure the ACL2 image you run is the same as the one listed as ACL2 in
 those environment variables!</li>

 <li>You may wish to set the environment variables for only the duration of your
 ACL2 session by using the "env" command.</li>

 <li>You may wish to edit some of the commands for better debugging purposes;
 e.g. you may modify the @(see set-inhibit-output-lst) command, or insert a
 @(see set-debugger-enable) command, etc.</li>

 <li>If you don't want your session to exit after a successful certification,
 replace the last form @('(er-progn (time$ (certify-book ...') with just the
 @('(time$ (certify-book ...))') part.</li>

 </ul>


 <h3>Further Resources</h3>

 <p>The build system is largely based on @(see BUILD::cert.pl).  There is
 considerable documentation about @('cert.pl'), and we highly recommend using it
 to manage your own ACL2 projects.</p>

 <p>The main build script is @('books/GNUmakefile').  There are many comments at
 the start of this file, and you can also inspect it to see what targets are
 available.</p>

 <p>Please feel absolutely free to contact the @(see acl2-help) mailing list
 with any questions about building the community books.</p>")

(defxdoc books-certification-alt
  :parents (books-certification)
  :short "Alternate instructions for certifying the @(see community-books),
 from the perspective of the @('acl2-sources') directory."
  :long "<p>WARNING: Parts of this documentation are probably obsolete, but parts
 are still relevant.  See @(see books-certification) as the primary source of
 information on how to certify the @(see community-books).</p>

 <p>For background on the ACL2 community books, see @(see community-books).
 Here we explain how to certify those books, or some of those books, with ACL2.
 We thank Bishop Brock, Jared Davis, and Sol Swords for their substantial
 contributions to this methodology.  See @('books/GNUmakefile'), in the
 community books, for more about ``Credits and History'', and for additional
 technical details not covered in this topic.</p>

 <p>For more information about installing ACL2, see @(see installation).  For
 information about so-called ``classic ACL2 `make'-based certification'', which
 provides support for certifying directories of books but may disappear in a
 future ACL2 release, see @(see books-certification-classic).</p>

 <p><b>The Basics</b></p>

 <p>We make the following assumptions.</p>

 <ul>
  <li>Gnu `make' is available on your system via the `make' command
 (rather than some other flavor of `make').  (Execute `@('make --version') to
 verify this.)</li>

  <li>You have built or obtained an ACL2 executable.</li>

  <li>The ACL2 @(see community-books) are installed in the @('books/')
 subdirectory of your ACL2 distribution, as is the case when you have followed
 the standard @(see installation) instructions.</li> </ul>

 <box><p>Note: All commands shown below are issued in the top-level (ACL2
 sources) directory of your ACL2 distribution.</p></box>

 <p>By default the ACL2 executable is file @('saved_acl2') in your ACL2
 sources directory, and you can issue the following command to the shell in
 order to do a ``regression run'' that certifies all of the community books
 using that executable.</p>

 @({
  make regression
 })

 <p>Better yet, save a log file in case there are problems, for example as
 follows.</p>

 @({
  (make regression) >& make-regression.log
 })

 <p>or perhaps better yet:</p>

 @({
  (time nice make regression) >& make-regression.log
 })

 <p>For the sake of brevity, below we'll skip mentioning any of `@('time')',
 `@('nice')', or `@('>& make-regression.log')'.  But saving a log file, in
 particular, is useful in case you encounter problems to report.</p>

 <p>If you fetched the community books using git, then you will have a
 directory such @('books/workshops/') that is not necessary for certifying the
 most widely-included books.  You can certify just such books as follows.</p>

 @({
  (time nice make basic) >& make-basic.log
 })

 <p>Whether you use target `@('regression')' or target `@('basic')', then for
 each book @('foo.lisp') whose certification is attempted, a file
 @('foo.cert.out') in the same directory will contain the output from the
 book's certification attempt.</p>

 <p>A regression run may take a few hours, but if you have a multiprocessing
 computer, you can speed it up by certifying some books in parallel, by
 providing a value for `make' option @('-j').  For example, if you have 8
 hardware threads then you might want to issue the following command.</p>

 @({
  make regression -j 8
 })

 <p><b>Specifying the ACL2 Executable</b></p>

 <p>If your ACL2 executable is not file @('saved_acl2') in the ACL2 sources
 directory, then you will need to specify that executable.  You can do that by
 setting variable @('ACL2'), either as an environment variable or, as displayed
 below, as a `make' variable.  Either way, you will need to avoid relative
 pathnames.  For example, the first two forms below are legal, but the third is
 not, assuming that @('my-acl2') is on your @('PATH') in a Unix-like
 environment (e.g., linux or MacOS) and that @('my-saved_acl2') is just a
 pathname relative to your ACL2 sources directory, which is not on your
 path.</p>

 @({
  make regression -j 8 ACL2=my-acl2
  make regression -j 8 ACL2=/u/smith/bin/acl2
  # The following only works if my-saved_acl2 is on your path (see above).
  make regression -j 8 ACL2=my-saved_acl2
 })

 <p><b>Cleaning</b></p>

 <p>You can delete files generated by book certification (including @('.cert')
 files, @('.out') files, compiled files, and more) by issuing the following
 command (again, in your ACL2 sources directory).</p>

 @({
  make clean-books
 })

 <p>Alternatively, if you want to cause such deletion and then do a regression,
 simply replace the `@('regression')' target by `@('regression-fresh').</p>

 <p>If however you only want to clean up generated files residing under a given
 directory (or its subdirectories, and recursively), you can issue the
 following command while standing in that directory, where @('DIR') is a
 pathname of your @('books') directory.</p>

 @({
  DIR/clean.pl
 })

 <p>For example, to clean up generated files under @('books/arithmetic'), you
 could do the following.</p>

 @({
  cd books/arithmetic
  ../clean.pl
  cd - # to return to the ACL2 sources directory, if you wish to do so
 })

 <p><b>Restricting to Specific Directories and Books</b></p>

 <p>You can specify which books you want certified by using any or all of the
 variables @('EXCLUDED_PREFIXES'), @('ACL2_BOOK_CERTS'), or
 @('ACL2_BOOK_DIRS').  First, the set of desired @('.cert') files is restricted
 to those that do not start with any string that is one of the words in the
 value of @('EXCLUDED_PREFIXES').  Then @('ACL2_BOOK_CERTS') and
 @('ACL2_BOOK_DIRS'), if supplied, specify which books should be certified, as
 illustrated by the following example.</p>

 @({
  make -j 8 regression-fresh \
   ACL2_BOOK_DIRS="symbolic paco" \
   ACL2_BOOK_CERTS=" \
    workshops/2006/cowles-gamboa-euclid/Euclid/ed6a.cert \
    workshops/2006/cowles-gamboa-euclid/Euclid/ed4bb.cert \
    "
 })

 <p>Then all book in directories @('symbolic') and @('paco') will be certified,
 as will the books @('workshops/2006/cowles-gamboa-euclid/Euclid/ed6a.lisp')
 and @('workshops/2006/cowles-gamboa-euclid/Euclid/ed4bb.lisp').  Note that all
 pathnames should be relative to your community books directory; in particular,
 they should not be absolute pathnames.  Also notice the @('.cert') extension
 used in files supplied for @('ACL2_BOOK_CERTS').</p>

 <p>Alternatively, you may wish to invoke @('books/cert.pl') while standing in
 a directory under which you want to certify books.  This will certify not only
 those books, but all supporting books &mdash; even those not under the current
 directory &mdash; that do not have up-to-date @('.cert') files.  The following
 is a simple command to invoke that will certify all books in the current
 directory, where if the @('books/') directory is not on your path, you will
 need to provide a suitable filename, e.g. @('../../cert.pl') or
 @('~/acl2/books/cert.pl').</p>

 @({
  cert.pl -j 4 *.lisp
 })

 <p>Here is a more complex command, which illustrates a way to certify books in
 subdirectories (as well as the current directory), the use of provisional
 certification (see @(see provisional-certification)), and `make'-level
 parallelism (in this case specifying four parallel processes).</p>

 @({
  cert.pl --pcert-all -j 4 `find . -name '*.lisp'`
 })

 <p>Note that with this approach, unlike classic ACL2 `make'-based
 certification (see @(see books-certification-classic), out-of-date @('.cert')
 files that are not under the current directory will also be built.  For
 documentation of @('cert.pl') invoke:</p>

 @({
  cert.pl -h
 })

 <p>See the top of @('cert.pl') for authorship and copyright information.</p>

 <p>Finally, we give a brief summary of how to use so-called ``classic ACL2
 `make'-based certification'' for community books; see @(see
 books-certification-classic) for details.  Note that support for this approach
 might be eliminated in a future ACL2 release.  We welcome comments from the
 ACL2 community about whether or not that would be a good thing to do.  See the
 discussion above about @('ACL2_BOOK_DIRS') for the ``modern'' way to
 accomplish the same thing.</p>

 <p>Many community book directories have a @('Makefile').  If you modify books
 only in such a directory, you can recertify by standing in that directory and
 issuing a `make' command.  This command can optionally specify an ACL2
 executable as well as parallelism, for example as follows, where the first
 line (@('make clean')) is optional.</p>

 @({
  make clean
  (time nice make -j 8 ACL2=my-acl2)
 })

 <p><b>ACL2 Customization Files</b></p>

 <p>By default, your acl2-customization file (see @(see acl2-customization)) is
 ignored by all flavors of ``@('make regression')''.  However, you can specify
 the use of an acl2-customization file by setting the value of environment
 variable @('ACL2_CUSTOMIZATION') to the empty string, indicating a default
 such file, or to the desired absolute pathname.  For example:</p>

 @({
  make regression ACL2_CUSTOMIZATION=''
  make regression ACL2_CUSTOMIZATION='~/acl2-customization.lisp'
 })

 <p><b>Regressions for Variants of ACL2</b></p>

 <p>The discussion above also pertains to using ACL2(p) (see @(see parallel))
 or ACL2(r) (see @(see real)), in which case the default is @('saved_acl2p') or
 @('saved_acl2r') respectively, rather than @('saved_acl2').  However, we
 recommend that you use ACL2, not ACL2(p), for your regression.  Then you can
 use ACL2(p) for your own proof developments.  However, if you want to use
 ACL2(p) or for your regression, see @(see
 waterfall-parallelism-for-book-certification).</p>

 <p><b>Provisional Certification</b></p>

 <p>To use provisional certification (see @(see provisional-certification)),
 supply @('ACL2_PCERT=t') with your `make' command.  Here is an example.</p>

 @({
  time nice make regression -j 4 ACL2_BOOK_DIRS=deduction ACL2_PCERT=t
 })

 <p><b>Miscellany</b></p>

 <p>Other control of the certification process may be found by perusing
 community books file @('books/make_cert').  In particular, the @('INHIBIT')
 variable may be set to a call of @(tsee set-inhibit-output-lst), for example
 as follows to obtain the output one would get by default in an (interactive)
 ACL2 session.</p>

 @({
  time nice make regression -j 4 ACL2_BOOK_DIRS=arithmetic \
    INHIBIT='(set-inhibit-output-lst proof-tree)'
 })

 <p><b>Troubleshooting</b></p>

 <p>If you run into problems, you can get help by joining the @('acl2-help')
 email list (follow the link from the ACL2 home page) and sending a message to
 that list.  Also consider trying another version of GNU `make'; for example,
 we have found that versions 3.81 and 3.82 sometimes cause errors on Linux
 where version 3.80 does not.  Note however that Version 3.80 does not print
 certain informational messages that are printed by later versions.</p>")

(defxdoc books-certification-classic
  :parents (books-certification)
  :short "Classic ACL2 `make'-based certification of @(see books)"
  :long "<p>This @(see documentation) topic explains an approach to certifying
 directories of books, which we call ``classic ACL2 `make'-based
 certification''.</p>

 <p>Warning: The capability described in this section might be replaced at any
 time by a capability based on corresponding support for community books (see
 @(see books-certification)).  If you think that would be a hardship, please
 contact the ACL2 implementors.</p>

 <p>This topic discusses a way to certify a directory of books other than the
 ACL2 community books.  See @(see books-certification) for how to certify the
 set of ACL2 community @(see books).  There is also a section in that @(see
 documentation) topic, ``Restricting to Specific Directories and Books'', that
 provides an alternative to classic ACL2 `make'-based certification (as
 discussed in the present topic) for certifying specified sets of books.</p>

 <p>We assume here a familiarity with Unix/Linux `make'.  We also assume that
 you are using GNU `make' rather than some other flavor of `make'.  And
 finally, we assume, as is typically the case by following the standard @(see
 installation) instructions, that you install the ACL2 community books in the
 @('books/') subdirectory of your ACL2 distribution.  We will refer below to
 that directory as @('BOOKS').</p>

 <p>In summary: to use `make' to certify @(see books) under a given directory,
 you may create a simple Makefile in that directory (as explained below) so
 that when you stand in that directory, you can submit the command, `make', to
 certify those books.  If you have a multi-processor machine or the like, then
 you can use the `@('-j') flag `make'-level parallelism by specifying the
 number of concurrent processes.  For example:</p>

 @({
  make -j 4
 })

 <p>For each book @('foo.lisp'), a file @('foo.out') in the same directory as
 @('foo.lisp') will contain the output from the corresponding certification
 attempt.  If you have previously executed such a command, then you might first
 want to delete @(see certificate) files and other generated files by executing
 the following command.</p>

 @({
  make clean
 })

 <p>Note that when you run `make', then by default, the first error will cause
 the process to stop.  You can use @('make -i') to force `make' to ignore
 errors, thus continuing past them.  Or, use @('make -k') to keep going, but
 skipping certification for any book that includes another whose certification
 has failed.</p>

 <p>By default, your acl2-customization file (see @(see acl2-customization)) is
 ignored by such `make' commands.  However, you can specify the use of an
 acl2-customization file by setting the value of environment variable
 @('ACL2_CUSTOMIZATION') to the empty string, indicating a default such file,
 or to the desired absolute pathname.  For example:</p>

 @({
  make ACL2_CUSTOMIZATION=''
  make ACL2_CUSTOMIZATION='~/acl2-customization.lisp'
 })

 <p>We now discuss how to create makefiles to support `make' commands as
 discussed above.</p>

 <p>First we give five steps for creating a @('Makefile') to support
 certification of a directory of books, without subdirectories.  For examples
 of such Makefiles you can look in community book directories (which, however,
 might disappear in future versions of ACL2).</p>

 <blockquote><p>1. Include the file @('Makefile-generic') from the @('books/')
 subdirectory of your ACL2 sources directory, but first perhaps define the
 variable `@('ACL2')'.  Consider the following example.</p>

 @({
  ACL2 ?= /Users/john_doe/acl2/acl2-sources/saved_acl2
  include /Users/john_doe/acl2/acl2-sources/books/Makefile-generic
 })

 <p>In this example, you can omit the first line, because the default ACL2
 executable is file @('saved_acl2') in the directory immediately above the
 directory of the specified @('Makefile-generic') file.  Indeed, that is the
 common case.  Note the use of @('?=') instead of @('=') or @(':='), so that
 @('ACL2') can instead be defined by the environment or provided on the command
 line as part of the `make' command.</p>

 <p>2. (Optional; usually skipped.)  Set the @('INHIBIT') variable if you want
 to see more than the @(see summary) output.  For example, if you want to see
 the same output as you would normally see at the terminal, put this line in
 your Makefile after the `@('include')' lines.</p>

 @({
  INHIBIT = (assign inhibit-output-lst (list (quote proof-tree)))
 })

 <p>For other values to use for @('INHIBIT'), see @(see set-inhibit-output-lst)
 and see the original setting of @('INHIBIT') in
 @('books/Makefile-generic').</p>

 <p>3. Specify the books to be certified.  Normally, every file with extension
 @('.lisp') will be a book that you want to certify, in which case you can skip
 this step.  Otherwise, put a line in your @('Makefile') after the ones above
 that specifies the books to be certified.  The following example, from an old
 version of community books file @('books/finite-set-theory/osets/Makefile'),
 should make this clear.</p>

 @({
  BOOKS = computed-hints fast instance map membership outer primitives \
          quantify set-order sets sort
 })

 <p>But better yet, use the extension @('.lsp') for any Lisp or ACL2 files that
 are not to be certified, so that the definition of @('BOOKS') can be
 omitted.</p>

 <p>4. Create @('.acl2') files for books that are to be certified in other than
 the initial ACL2 world (see @(see portcullis)).  For example, if you look in
 community books file @('books/arithmetic/equalities.acl2') you will see @(tsee
 defpkg) forms followed by a @(tsee certify-book) command, because it was
 determined that @(tsee defpkg) forms were necessary in the certification world
 in order to certify the @('equalities') book.  In general, for each
 @('<book-name>.lisp') whose certification requires a non-initial certification
 world, you will need a corresponding @('<book-name>.acl2') file that ends with
 the appropriate @(tsee certify-book) command.</p>

 <p>You also have the option of creating a file @('cert.acl2') that has a
 special role.  When file @('<book-name>.lisp') is certified, if there is no
 file @('<book-name>.acl2') but there is a file @('cert.acl2'), then
 @('cert.acl2') will be used as @('<book-name>.acl2') would have been used, as
 described in the preceding paragraph, except that the appropriate @(tsee
 certify-book) command will be generated automatically.  Thus, no
 @('certify-book') command should occur in @('cert.acl2').</p>

 <p>It is actually allowed to put raw lisp forms in a @('.acl2') file
 (presumably preceded by @(':q') or @('(value :q)') and followed by @('(lp)')).
 But this is not recommended (see @(see q)); we make no guarantees about
 certification performed any time after raw Lisp has been entered in the ACL2
 session.</p>

 <p>5. Generally, the next step is to include the following line after the
 `@('include')' of @('Makefile-generic') (see the first step above).</p>

 @({
  -include Makefile-deps
 })

 <p>This will cause `make' to create and then include a file @('Makefile-deps')
 that contains ``dependency'' lines needed by `make'.  If those dependencies
 are somehow flawed, it may be because you have @(tsee include-book) forms that
 are not truly including books, for example in multi-line comments
 (@('#|..|#')).  These will be ignored if preceded by a semicolon (@(';')), or
 if you add a line break after ``@('include-book').''  But instead of adding
 the `@('-include')' line above, you can create dependency lines yourself by
 running the command</p>

 @({
  make dependencies
 })

 <p>and pasting the result into the end of your @('Makefile'), and editing as
 you see fit.</p></blockquote>

 <p>This concludes the basic instructions for creating a @('Makefile') in a
 directory including books.  Here are some other capabilities offered by
 community books file @('books/Makefile-subdirs').  Not included below is a
 discussion of how to increase parallelism by avoiding the need to certify
 included books before certifying a given book; see @(see
 provisional-certification).</p>

 <p><b>Subdirectory Support</b></p>

 <p>There is support for using `make' to certify books in subdirectories.
 Consider the following example.</p>

 @({
  DIRS = pass1 bind-free floor-mod
  include ../Makefile-subdirs
 })

 <p>This indicates that we are to run `make' in subdirectories @('pass1/'),
 @('bind-free/'), and @('floor-mod/') of the current directory.</p>

 <p>You can combine this subdirectory support with the support already
 discussed for certifying books in the top-level directory.  Here is an
 example, which as of this writing is in community books file
 @('books/arithmetic-3/Makefile') contains the following lines.</p>

 @({
  arith-top: top all
  all: top

  DIRS = pass1 bind-free floor-mod
  include ../Makefile-subdirs
  include ../Makefile-generic

  -include Makefile-deps
 })

 <p>The `@('top')' target is defined in @('../Makefile-subdirs') to call `make'
 in each subdirectory specified in @('DIRS').  We have set the default target
 in the example above to a new name, @('arith-top'), that makes that @('top')
 target before making the `@('all')' target which, in turn, is the default
 target in any @('Makefile-generic'), and is responsible for certifying books
 in the current directory as discussed in the five steps displayed above.</p>

 <p>Use @('Makefile-psubdirs') instead of @('Makefile-subdirs') if
 certification of a book in a subdirectory never depends on certification of a
 book in a different subdirectory, because then the @('-j') option of `make'
 can allow subdirectories to be processed in parallel.</p>

 <p><b>Cleaning Up</b></p>

 <p>We note that there is a @('clean') target.  Thus,</p>

 @({
  make clean
 })

 <p>will remove generated files including @('.cert'), @('.out') files, and
 compiled files.</p>

 <p><b>System Books</b></p>

 <p>An environment variable @('ACL2_SYSTEM_BOOKS') is generally set
 automatically, so you can probably skip reading the following paragraph unless
 your attempt to certify books fails to locate those books properly.</p>

 <p>The environment variable @('ACL2_SYSTEM_BOOKS') can be set to the top-level
 directory of the ACL2 community books.  A Unix-style pathname, typically
 ending in @('books/') or @('books'), is permissible.  In most cases, your ACL2
 executable is a small script in which you can set this environment variable
 just above the line on which the actual ACL2 image is invoked, for
 example:</p>

 @({
  export ACL2_SYSTEM_BOOKS
  ACL2_SYSTEM_BOOKS=/home/acl2/v3-2/acl2-sources/books
 })

 <p>However, you can also set @('ACL2_SYSTEM_BOOKS') as a `make' variable, by
 setting it in your @('Makefile') before the first target definition, e.g.:</p>

 @({
  ACL2_SYSTEM_BOOKS ?= /home/acl2/v3-2/acl2-sources/books
 })

 <p><b>Compilation Support</b></p>

 <p>The file @('books/Makefile-generic') provides support for compiling books
 that are already certified (but see @(see compilation) for an exception).  For
 example, suppose that you have certified books using GCL as the host Lisp,
 resulting in compiled files with the @('.o') extension.  Now suppose you would
 like to compile the books for Allegro Common Lisp, whose compiled files have
 the @('.fasl') extension.  The following command will work if you have
 included @('books/Makefile-generic') in your @('Makefile').</p>

 @({
  make fasl
 })

 <p>In general, the compiled file extension for a Lisp supported by ACL2 will
 be a target name for building compiled files for all your books (after
 certifying the books, if not already up-to-date on certification).</p>

 <p>If you run into problems, you can get help by joining the @('acl2-help')
 email list (follow the link from the ACL2 home page) and sending a message to
 that list.  Also consider trying another version of GNU `make'; for example,
 we have found that versions 3.81 and 3.82 sometimes cause errors on Linux
 where version 3.80 does not.</p>")

(defxdoc books-reference
  :parents (books)
  :short "Reference guide for ACL2 functionality related to books, e.g.,
@(see include-book), @(see certify-book), @(see cbd), etc.")

(defxdoc books-tour
  :parents (books)
  :short "The <i>guided tour</i> of concepts related to ACL2 @(see books)."
  :long "<p>The tour begins with @(see book-example).</p>")

(defxdoc boole$
  :parents (numbers acl2-built-ins)
  :short "Perform a bit-wise logical operation on 2 two's complement integers"
  :long "<p>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 the analogous Common Lisp function
 @(`(:raw (clhs "Body/f_boole.htm" "boole"))`) in the @(`(:raw (clhs ""
 "Common Lisp Hyperspec"))`).  Note that the values of @('op') for
 @('boole$') are ACL2 constants, rather than corresponding values of @('op')
 for the Common Lisp function @('boole').</p>

 @({
  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
 })

 <p>The guard of @('boole$') specifies that @('op') is the value of one of the
 constants above and that @('x') and @('y') are integers.</p>

 <p>See any Common Lisp documentation for analogous information about Common
 Lisp function @('boole').</p>

 @(def boole$)")

(defxdoc boolean-listp
  :parents (booleanp lists acl2-built-ins)
  :short "Recognizer for a true list of booleans"
  :long "<p>The predicate @('boolean-listp') tests whether its argument is a
 @(tsee true-listp) of objects each or which satisfies @(tsee booleanp), i.e.,
 is @('t') or @('nil').</p>

 @(def boolean-listp)")

(defxdoc booleanp
  :parents (basics acl2-built-ins)
  :short "Recognizer for booleans"
  :long "<p>@('(Booleanp x)') is @('t') if @('x') is @('t') or @('nil'), and is
 @('nil') otherwise.</p>

 <p>See @(see 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?</p>

 @(def booleanp)")

(defxdoc bounders
  :parents (tau-system)
  :short "Intervals, bounder functions, and bounder correctness"
  :long "<code>
 <i>Bounder Forms 1 and 2</i>:
 (implies (and (tau-intervalp i1)
               ...
               (or (equal (tau-interval-dom i1) 'dom1-1)
                   ...)
               ...
               (in-tau-intervalp x1 i1)
               ...)
          (and (tau-intervalp (bounder-fn i1 ...))
               (in-tau-intervalp <i>target</i>
                                 (bounder-fn i1 ...))))
 </code>

 <p>where <i>target</i> is either @('(fn x1 ... y1 ...)') or @('(mv-nth 'n (fn
 x1 ... y1 ...))'), depending on whether we are in the <i>Form 1</i> or <i>Form
 2</i> case, respectively.  However, the shape above is meant just as a
 reminder.  Details are given below.</p>

 <p>This topic first explains the basic shape of <i>Bounder Form 1</i>.  Then
 it illustrates <i>Bounder Form 2</i>.  Finally, it deals briefly with proving
 bounder correctness theorems.  The community book
 @('tau-bounders/elementary-bounders') contains bounders for various elementary
 functions including @(tsee +), @(tsee *), @(tsee /), @(tsee FLOOR), @(tsee
 MOD), @(tsee LOGAND), @(tsee LOGNOT), @(tsee LOGIOR), @(tsee LOGORC1), @(tsee
 LOGEQV), @(tsee LOGXOR), and @(tsee ASH).  You might look at or include this
 book to see more example theorems, to see how proofs of such theorems are
 managed, and to experiment with their effects on proving theorems involving
 arithmetic over finite or half-finite intervals.</p>

 <p>A bounder correctness theorem establishes that @('bounder-fn') is a
 ``bounder'' for the function @('fn').  That means that when trying to compute
 a tau for a call of @('fn') (or, in the case of <i>Form 2</i>, for the
 @('n')th component of the multiple-value vector returned by a call of @('fn'))
 the tau system can call @('bounder-fn') on the intervals containing certain
 arguments of @('fn').</p>

 <p>Let us start with an example.  Let @('fn') be the addition function, @('+')
 (actually, @(tsee binary-+)).  Consider the target term @('(+ x y)') and
 contemplate the question: if you know intervals containing @('x') and @('y'),
 say @('intx') and @('inty') respectively, what is an interval containing their
 sum?  The answer is pretty easy to state in English: the domain of the answer
 interval is the less restrictive of the domains of @('intx') and @('inty').
 The lower bound of the answer interval is the sum of the lower bounds of
 @('intx') and @('inty'), and the lower relation is the stronger of the lower
 relations of @('intx') and @('inty').  Analogous comments define the upper
 bound and relation of the answer interval.  So for example, if @('x') is an
 @('INTEGERP') such that @('0 <= x <= 10') and @('y') is a @('RATIONALP') such
 that @('0 < y <= 20'), then @('(+ x y)') is a @('RATIONALP') such that @('0 <
 (+ x y) <= 30').</p>

 <p>Defining this precisely is more tedious than describing it in English
 because one must make precise the notions of ``less restrictive'' domains,
 ``weaker'' relations, and the possibility that either or both of the bounds
 could be ``infinite.''  But we can easily imagine defining the function
 @('bounder-for-+') that returns the answer interval described, given @('intx')
 and @('inty').</p>

 <p>Then the following <i>Bounder Form 1</i> formula establishes the
 correctness of @('bounder-for-+') and allows the tau system to use it to
 produce bounds in the tau computed for @('+')-expressions:</p>

 @({
  (implies (and (tau-intervalp intx)
                (tau-intervalp inty)
                (in-tau-intervalp x intx)
                (in-tau-intervalp y inty))
           (and (tau-intervalp (bounder-for-+ intx inty))
                (in-tau-intervalp (+ x y)
                                  (bounder-for-+ intx inty))))
 })

 <p>For example, suppose we have a formula with the following hypotheses</p>

 @({
  (and (integerp a)
       (<= 0 a)
       (<= a 10)
       (rationalp b)
       (< 0 b)
       (<= b 20))
 })

 <p>and suppose the tau system encounters the term @('(+ a b)').  When the term
 is encountered, the tau for @('a') would include an @('INTEGERP') interval such
 that @('0 <= a <= 10') and the tau for @('b') would include a @('RATIONALP')
 interval such that @('0 < b <= 20').  In its most primitive configuration, the
 tau system would only know that the tau for @('(+ a b)') includes the
 recognizer @('RATIONALP') (and all that it is known to imply).  But after the
 bounder theorem above is proved and available as a @(':tau-system') rule the
 tau system would infer that @('(+ a b)') was in the @('RATIONALP') interval
 such that @('0 < (+ a b) <= 30').</p>

 <p>Thus, by defining bounder functions and proving them correct the user can
 give the tau system the ability to compute the bounds on function calls as a
 function of the known bounds on their actuals.</p>

 <p>It is sometimes useful to restrict the domains of the intervals to be
 considered.  For example, in bounding @('*')-expressions it is simplifying to
 restrict one's attention to intervals over the integers or rationals (and thus
 exclude the complex rationals so one need not think about the getting negative
 bounds by multiplying two ``positive'' complex rationals or how to ``round
 up'' from complex bounds to the rationals required by our intervals).</p>

 <p>If we were to define @('bounder-for-*') so that it works correctly to bound
 @('*')-expressions, but only for integer or rational arguments, its
 correctness theorem would be:</p>

 @({
  (implies (and (tau-intervalp intx)                             ; (a)
                (tau-intervalp inty)
                (or (equal (tau-interval-dom intx) 'INTEGERP)    ; (b)
                    (equal (tau-interval-dom intx) 'RATIONALP))
                (or (equal (tau-interval-dom inty) 'INTEGERP)
                    (equal (tau-interval-dom inty) 'RATIONALP))
                (in-tau-intervalp x intx)                        ; (c)
                (in-tau-intervalp y inty))
           (and (tau-intervalp (bounder-for-* intx inty))       ; (d)
                (in-tau-intervalp (* x y)                        ; (e)
                                  (bounder-for-* intx inty))))
 })

 <p>In this case, @('bounder-for-*') would be applied to the intervals for
 @('x') and @('y') only if those intervals were over the integers or the
 rationals.</p>

 <p>The above theorem for @('bounder-for-*') begins to suggest the general form
 of a bounder theorem and we will use it to explain the general form.</p>

 <p>The hypotheses of a bounder theorem must be a conjunction and the conjuncts
 must be partitionable into three parts, (a), (b), and (c).  The conclusion,
 must be a conjunction, must contain at least two conjuncts, (d) and (e), and
 is allowed to contain others that are simply ignored for purposes of bounders.
 (See the note below about why we allow but ignore additional conjuncts in the
 conclusion.)</p>

 <p>Part (a) introduces some distinct ``interval variables,'' here called
 ``ivars,'' that are known to denote intervals; for the example above, the
 ivars are @('intx') and @('inty').  Each hypothesis in part (a) is of the form
 @('(TAU-INTERVALP ivar)').</p>

 <p>Part (b) allows us to restrict the domains of some of the intervals.  Each
 hypothesis in part (b) must be a disjunction and each of the disjuncts must be
 of the form @('(EQUAL (TAU-INTERVAL-DOM ivar) 'dom)'), where @('ivar') is one
 of the interval variables and @('dom') is one of @('INTEGERP'),
 @('RATIONALP'), @('ACL2-NUMBERP'), or @('NIL').  It is not necessary to
 restrict every interval variable.  Indeed, part (b) may be empty, as in the
 theorem for @('bounder-for-+') above.</p>

 <p>Part (c) consists of a set of @('(IN-TAU-INTERVALP avar ivar)') hypotheses
 where each @('avar') is a variable and no two hypotheses in part (c) use the
 same @('avar') or @('ivar').  We call the set of all such @('avar') the
 ``actual variables'' or ``avars.''  The avars and ivars must be distinct.
 Part (c) sets up a correspondence between the avars and the ivars, each avar
 is in an interval denoted by one ivar.</p>

 <p>Part (d) introduces the name of the bounder function, here
 @('bounder-for-*'), and the order of its ivar arguments.  We see that
 @('bounder-for-*') takes two arguments and they correspond, in order, to the
 intervals containing @('x') and @('y').  Part (d) also establishes that the
 bounder function always returns an interval under hypotheses (a), (b), and
 (c).  Note that it is sometimes useful to return the ``universal interval''
 (one that contains everything) if you don't want to compute a better interval
 for some case; see @(tsee tau-intervalp) or @(tsee in-tau-intervalp).</p>

 <p>Part (e) introduces the name of the function being bounded, here @('*'),
 and the order of its arguments.  It establishes that the function being
 bounded really is bounded by the interval computed by the bounder function.
 In general, the function being bounded may take additional arguments.  It is
 possible that the function being bounded takes some arguments that do not
 affect the bounds of its output.</p>

 <p>Thus, parts (c) and (e) together establish a mapping between the actuals of
 a call of the function being bounded and the intervals to be supplied to the
 bounder.</p>

 <p>The parts identified above may be presented in any order and the literals
 constituting those parts may be mingled.  Thus, for example, here is another
 version of the theorem above that generates the same bounding information for
 the tau system.  In this version, the hypotheses and conclusions are
 rearranged, @('bounder-for-*') takes its arguments in the opposite order, and
 the theorem includes an additional conclusion.</p>

 @({
  (implies (and (tau-intervalp intx)                             ; (a)
                (or (equal (tau-interval-dom intx) 'INTEGERP)    ; (b)
                    (equal (tau-interval-dom intx) 'RATIONALP))
                (in-tau-intervalp x intx)                        ; (c)

                (tau-intervalp inty)                             ; (a)
                (or (equal (tau-interval-dom inty) 'INTEGERP)    ; (b)
                    (equal (tau-interval-dom inty) 'RATIONALP))
                (in-tau-intervalp y inty))
           (and (in-tau-intervalp (* x y)                        ; (e)
                                  (bounder-for-* inty intx))
                (tau-intervalp (bounder-for-* inty intx))        ; (d)))

                (or (equal (tau-interval-dom (bounder-for-* inty intx))
                           'INTEGERP)
                    (equal (tau-interval-dom (bounder-for-* inty intx))
                           'RATIONALP))
 })

 <p><i>Note on why bounder forms allow additional conjuncts in the
 conclusion</i>: It is often the case that one creates bounders by composing
 other bounders.  To prove compositional bounds correct one must often prove
 more than the mere correctness of the components.  For example, one might need
 to prove that the domain of the new bounding interval is @('INTEGERP') or
 otherwise restricted.  We allow such ``unnecessary'' conclusions simply to
 save the user the burden of stating multiple theorems.</p>

 <p><i>An Illustration of Bounder Form 2</i>: Suppose @('(quad i)') is defined
 so that truncates the integer @('i') to the largest multiple of 4 weakly below
 @('i') and, additionally, returns the remainder.  For example, @('(quad 26)')
 returns @('(mv 24 2)').  Then here are bounders for each of its return
 values:</p>

 @({
  (defun quad-bounds-0 (i)
    (cond ((and (tau-interval-lo i)
                (<= 0 (tau-interval-lo i)))
           (make-tau-interval 'integerp nil 0 nil (tau-interval-hi i)))
          (t (make-tau-interval nil nil nil nil nil))))

  (defun quad-bounds-1 (i)
    (cond ((and (tau-interval-lo i)
                (<= 0 (tau-interval-lo i)))
           (make-tau-interval 'integerp nil 0 nil 3))
          (t (make-tau-interval nil nil nil nil nil))))
 })

 <p>Note that the bounders assume @('i') is an @('INTEGERP') and return the
 universal interval when @('i') is not a natural.</p>

 <p>As noted in the discussion below about how to prove bounder correctness
 theorems, proving these bounders correct will require an arithmetic book,
 e.g.,</p>

 @({
  (include-book "arithmetic-5/top" :dir :system)
 })

 <p>Here then are two bounder correctness theorems of <i>Form 2</i>:</p>

 @({
  (defthm quad-bounds-0-correct
    (implies (and (tau-intervalp i)
                  (equal (tau-interval-dom i) 'INTEGERP)
                  (in-tau-intervalp x i))
             (and (tau-intervalp (quad-bounds-0 i))
                  (in-tau-intervalp (mv-nth 0 (quad x))
                                    (quad-bounds-0 i))))
    :rule-classes :tau-system)

  (defthm quad-bounds-1-correct
    (implies (and (tau-intervalp i)
                  (equal (tau-interval-dom i) 'INTEGERP)
                  (in-tau-intervalp x i))
             (and (tau-intervalp (quad-bounds-1 i))
                  (in-tau-intervalp (mv-nth 1 (quad x)) (quad-bounds-1 i))))
    :rule-classes :tau-system)
 })

 <p>As noted above, if these bounders are to be used in constructing other
 bounders, we might include (in the first theorem) an additional concluding
 conjunct, such as</p>

 @({
  (equal (tau-interval-dom (quad-bounds-0 i)) 'INTEGERP)
 })

 <p>so that we can keep @('quad-bounds-0') disabled to allow us to use
 @('quad-bounds-0-correct') as a @(':rewrite') or other rule and still relieve
 hypotheses about the domain of the interval it produces.  These hypotheses
 would arise if some other verified bounder was called on the produced
 interval.  In addition, as noted below, we might replace the
 @(':rule-classes') above with</p>

 @({
  :rule-classes
   ((:rewrite)
    (:forward-chaining :trigger-terms ((quad-bounds-0 i))))
 })

 <p>Since the theorem is being stored as some kind of rule and since it
 satisfies the <i>Bounder Form 2</i> shape, it will additionally be stored as a
 @(':tau-system') rule.</p>

 <p><i>Note on proving bounder theorems</i>: Proving bounder theorems is just
 like proving any other arithmetic theorem and you will need whatever libraries
 are appropriate for the problem domain you are working in.  Do not expect the
 tau system to be of much use in proving bounder theorems.  A typical bounder
 theorem might require you to prove a subgoal like @('(< (fn x y) (g
 (tau-interval-hi int1) int2))').  But tau deals with inequalities relating
 terms to constants, e.g., @('(< ... 16)').  A bounder theorem is a sort of
 ``metatheorem'' about <i>how to construct</i> bounded intervals from other
 bounded intervals.  So when you undertake to define a bounder and prove it
 correct, go into the project with your eyes open!</p>

 <p>But bounder functions can be broadly divided into two classes, those
 defined in terms of arithmetic on the interval bounds and those defined in
 terms of other bounders.  For example, given that</p>

 @({
  (LOGXOR x y) = (LOGNOT (LOGEQV x y))
 })

 <p>an interval for bounding @('LOGXOR') can be constructed by composing the
 constructions of intervals for @('LOGEQV') and @('LOGNOT').  So some bounder
 correctness proofs will involve direct manipulation of arithmetic inequalities
 and others might involve appeal to the correctness of other bounders,
 depending on how the new bounder is defined.</p>

 <p>Regardless of which style of bounder we are dealing with, we have found it
 useful to prove the basic theorems relating the tau interval accessors to
 @(tsee MAKE-TAU-INTERVAL), e.g.,</p>

 @({
  (equal (tau-interval-dom (make-tau-interval dom lo-rel lo hi-rel hi)) dom)
 })

 <p>and then disable those functions to avoid seeing excessive @('car')s and
 @('cdr')s.</p>

 <p>When dealing with bounders defined in the direct, arithmetic style, we tend
 to keep @(tsee TAU-INTERVALP) and @(tsee IN-TAU-INTERVALP) enabled so they
 unfold and expose the algebra.</p>

 <p>When dealing with bounders defined compositionally in terms of other
 verified bounders, we tend to keep @(tsee TAU-INTERVALP) and @(tsee
 IN-TAU-INTERVALP) disabled so we can rely on the previously proved bounder
 theorems as rewrite and forward chaining rules.</p>

 <p>Note that this last remark means that when you prove bounder correctness
 theorems you should include corollaries that are useful @(':rewrite') and
 possibly @(':forward-chaining') rules if you anticipate using that bounder in
 more complex ones.  We tend to trigger the forward chaining with the bounder
 expression itself, rather than one of the hypotheses.  For example in the rule
 above for @('bounder-for-*') we would include @('(:forward-chaining
 :trigger-terms ((tau-bounder-expt2 int2)))') and let the @('in-tau-intervalp')
 hypotheses select the free variables @('x') and @('y').</p>")

(defxdoc break$
  :parents (errors acl2-built-ins)
  :short "Cause an immediate Lisp break"
  :long "<p>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 @(see
 set-debugger-enable).)  @('Break$') returns @('nil').  Note that upon
 returning to the ACL2 read-eval-print loop (for example, using @(':q') if the
 host Lisp is CCL), one will be at the top level even if one had been inside a
 recursive call of @(tsee ld) or a @(see wormhole).</p>

 @(def break$)")

(defxdoc break-lemma
  :parents (break-rewrite)
  :short "A quick introduction to breaking rewrite rules in ACL2"
  :long "@({
  Example:
  :brr t                          ; if you haven't done that yet
  :monitor (:rewrite lemma12) t   ; to install a break point on the
                                  ;   rule named (:rewrite lemma12)
  :monitor! (:rewrite lemma12) t  ; quiet version of :monitor that
                                  ;   invokes :brr t
 })

 <p>ACL2 does not support Nqthm's @('break-lemma') but supports a very similar
 and more powerful break facility.  Suppose some proof is failing; apparently
 some particular rule is not being used and you wish to learn why.  Then you
 need the ACL2 @(see break-rewrite) facility.  See @(see break-rewrite) and all
 of its associated @(':')@(tsee doc) topics for details.  The following basic
 steps are required.</p>

 <p>(1) To enable the ``break rewrite'' feature, you must first execute</p>

 @({
  ACL2 !>:brr t
 })

 <p>at the top-level of ACL2.  Equivalently, evaluate @('(brr t)').  @(see
 Break-rewrite) stays enabled until you disable it with @('(brr nil)').  When
 @(see break-rewrite) is enabled the ACL2 rewriter will run slower than normal
 but you will be able to @(see monitor) the attempts to apply specified
 rules.</p>

 <p>(2) Decide what @(see rune)s (see @(see rune)) you wish to @(see monitor).
 For example, you might want to know why @('(:rewrite lemma12 . 2)') is not
 being used in the attempted proof.  That, by the way, is the name of the
 second rewrite rule generated from the event named @('lemma12').</p>

 <p>The command</p>

 @({
  ACL2 !>:monitor (:rewrite lemma12 . 2) t
 })

 <p>will install an ``unconditional'' break point on that rule.  The ``@('t')''
 at the end of the command means it is unconditional, i.e., a break will occur
 every time the rule is tried.  ACL2 supports conditional breaks also, in which
 case the @('t') is replaced by an expression that evaluates to non-@('nil')
 when you wish for a break to occur.  See @(see monitor).  The above keyword
 command is, of course, equivalent to</p>

 @({
  ACL2 !>(monitor '(:rewrite lemma12 . 2) t)
 })

 <p>which you may also type.  You may install breaks on as many rules as you
 wish.  You must use @(tsee monitor) on each rule.  You may also change the
 break condition on a rule with @(tsee monitor).  Use @(tsee unmonitor) (see
 @(see unmonitor)) to remove a rule from the list of @(see monitor)ed
 rules.</p>

 <p>(3) Then try the proof again.  When a @(see monitor)ed rule is tried by the
 rewriter you will enter an interactive break, called @(see break-rewrite).
 See @(see break-rewrite) for a detailed description.  Very simply, @(see
 break-rewrite) lets you inspect the context of the attempted application both
 before and after the attempt.  When @(see break-rewrite) is entered it will
 print out the ``target'' term being rewritten.  If you type @(':go') @(see
 break-rewrite) will try the rule and then exit, telling you (a) whether the
 rule was applied, (b) if so, how the target was rewritten, and (c) if not, why
 the rule failed.  There are many other commands.  See @(see brr-commands).</p>

 <p>(4) When you have finished using the @(see break-rewrite) feature you
 should disable it to speed up the rewriter.  You can disable it with</p>

 @({
  ACL2 !>:brr nil
 })

 <p>The list of @(see monitor)ed rules and their break conditions persists but
 is ignored.  If you enable @(see break-rewrite) later, the list of @(see
 monitor)ed rules will be displayed and will be used again by rewrite.</p>

 <p>You should disable the @(see break-rewrite) feature whenever you are not
 intending to use it, even if the list of @(see monitor)ed rules is empty,
 because the rewriter is slowed down as long as @(see break-rewrite) is
 enabled.</p>

 <p>If you get a stack overflow, see @(see cw-gstack).</p>")

(defxdoc break-on-error
  :parents (trace acl2-built-ins)
  :short "Break when encountering a hard or soft error caused by ACL2"
  :long "@({
  General forms:
  (break-on-error t)    ; installs a trace causing a continuable error (break)
                        ;   when an error is invoked by ACL2.
  (break-on-error)      ; same as above
  (break-on-error :all) ; same as above, but even when inside the prover
  (break-on-error nil)  ; uninstall any above trace
 })

 <p>Evaluation of @('(break-on-error :all)') generates a suitable @(see trace)
 of error functions, so that the Lisp debugger is entered whenever ACL2 calls
 them.  You can then continue the interrupted computation by suitable exit from
 the debugger (with a command that depends on the host Lisp).  Evaluation of
 @('(Break-on-error t)'), or equivalently, @('(break-on-error)'), is similar
 except that certain errors are ignored when inside the theorem prover; this is
 probably preferable, in general, to @('(break-on-error :all)').  Finally,
 evaluation of @('(break-on-error nil)') removes those traces.</p>

 <p><b>Remarks</b>.</p>

 <ul>

 <li>The argument, if supplied, is evaluated and must evaluate to @('t'),
 @('nil'), or @(':all').</li>

 <li>For technical reasons, you may see breaks or error messages more than
 once.</li>

 <li>It is an error to call @('break-on-error') while in @(see raw-mode).</li>

 <li>@('Break-on-error') is implemented using ACL2 @(tsee trace!), which is a
 version of @(tsee trace$) that uses a @(see ttag) and hence generates a
 ``@('TTAG NOTE')'' message.  You can use @(':')@(tsee trans1) to see the
 @('trace!') call generated by a given call of @('break-on-error').  Evaluate
 @('(trace$)') if you want to see the current trace specs.</li>

 </ul>

 <p>You are of course welcome to define your own version of @('break-on-error')
 by modifying a copy of the source definition (search for ``@('(defmacro
 break-on-error)')'' in ACL2 source file @('other-events.lisp')).  Please feel
 free to send your version of @('break-on-error') to the ACL2 implementors, to
 consider for inclusion into ACL2.</p>

 <p>Also see @(see set-debugger-enable) for how to get raw-Lisp backtrace
 information when an error occurs as a result of @('break-on-error'), or even
 of a raw Lisp error, by calling @('set-debugger-enable') with argument
 @(':bt'), @(':bt-break'), or @(':break-bt').  Note that for ACL2 errors (as
 opposed to raw Lisp errors), i.e. errors affected by @('break-on-error'), all
 three of those keyword values are treated equivalently (and, all are ignored
 for non-ANSI GCL; see @(see set-debugger-enable)).</p>")

(defxdoc break-rewrite
  :parents (debugging)
  :short "A version of the ACL2 rewriter with interactive breaks"
  :long "<p>ACL2 allows the user to @(see monitor) the application of @(see
 rewrite), @(see definition), and @(see linear) rules.  When the rewriter is
 about to try to apply an @(tsee enable)d @(see monitor)ed rule, it can trigger
 an interactive break managed by a version of the rewriter called
 &ldquo;break-rewrite&rdquo;.  These breaks can be caused by</p>

 <ul>
 <li>failure of a rewrite rule's equivalence relation
 to be a known refinement of the permitted relations,</li>
 <li>failure of
 a rule's triggering pattern to match the target term while &ldquo;almost&rdquo;
 matching,</li>
 <li>failure to relieve the hypotheses of the rule, or</li>
 <li>failure of any of several heuristic checks to prevent looping in the rewriter.</li>
 </ul>

 <p>From within this read-eval-print loop you can inspect the context, attempt
 to apply the rule, and see what happens.  This interactive loop is technically
 just a call of the standard ACL2 read-eval-print loop, @(tsee ld), on a
 ``@(see wormhole) @(see state)'' (see @(see wormhole)).  While in
 break-rewrite, certain keyword commands are available for accessing
 information about the context in which the lemma is being tried.  These
 keywords are called break-rewrite ``commands''; see @(see brr-commands).
 Interactive breaks occur only if the @('break-rewrite') utility is turned
 on (see @(tsee brr)), a monitored rune is being considered by the rewriter,
 and the break conditions specified in the monitor are satisfied (see @(tsee
 monitor)).</p>

 <p>The following utilities can also be helpful for proof @(see debugging).</p>

 <ul>

 <li>@(tsee Dmr) (Dynamically Monitor Rewrites) allows you to watch progress of
 the rewriter in real time.</li>

 <li>The @(see proof-builder) allows you to interactively construct a
 proof.</li>

 <li>@(tsee with-brr-data) helps you to find the source of a term in prover
 output.</li>

 </ul>

 <p>To abort from inside break-rewrite at any time, execute @(':')@(tsee
 a!).</p>

 <p>Output from break-rewrite is abbreviated by default, but that can be
 changed.  See @(see set-brr-evisc-tuple).</p>

 <p>When the break-rewrite facility is turned on (see @(tsee brr)), the
 rewriter performs more sluggishly than when break-rewrite is turned off.
 Therefore if you have done @('(brr t)') to debug a rewriting problem, we
 recommend that you do @('(brr nil)') after the situation is remedied and you
 resume normal proof development.</p>

 <p>For further information, see the related @(':')@(tsee doc) topics listed
 below.</p>

 <p><i>Advice to Developers and Maintainers of ACL2</i>: If you intend to
 modify break-rewrite, we strongly urge you to read the Essay on Break-Rewrite
 in the source code file @('rewrite.lisp').  There we explain the abstraction
 provided by break-rewrite, how it is implemented as a state machine operating
 in a wormhole, and some low-level tools for inspecting the state of
 break-rewrite.  Attempts to add new features without understanding virtually
 everything about the implementation is most likely to create a mess.</p>

 <p>It is possible to cause the ACL2 rewriter to @(see monitor) the attempted
 application of selected rules.  When such a rule is about to be tried, the
 rewriter evaluates its break condition and if the result is non-@('nil'), an
 interactive read-eval-print loop is entered.</p>

 <p>Break-rewrite permits the user to inspect the current @(see state) by
 evaluating break-rewrite commands.  Type @(':help') in break-rewrite to see
 what the break-rewrite commands are.  However, break-rewrite is actually just
 a call of the general ACL2 read-eval-print loop, @(tsee ld), on a certain
 @(see state) and the break-rewrite commands are simply aliases provided by
 @('ld-keyword-aliases') @(see table) (see @(see ld-keyword-aliases)).  See
 @(see ld) for details about this read-eval-print loop.  Thus, with a few
 exceptions, anything you can do at the ACL2 top-level can be done within
 break-rewrite.  For example, you can evaluate arbitrary expressions, use the
 keyword command hack, access @(see documentation), print @(see events), and
 even define functions and prove theorems.  However, the ``certain @(see
 state)'' upon which @(tsee ld) was called is a ``wormhole state'' (see @(see
 wormhole)) because break-rewrite is not allowed to have any effect upon the
 behavior of rewrite.  What this means, at a high level, is that break-rewrite
 operates on a copy of the @(see state) being used by rewrite and when
 break-rewrite exits the @(see wormhole) closes and the @(see state)
 ``produced'' by break-rewrite disappears.  For example, all invocations of
 @(tsee trace$) and @(tsee untrace$) that are made during such a break are
 undone when proceeding from that break (including when proceeding via the
 @(':eval') brr-command).  Thus, break-rewrite lets you query the state of the
 rewriter and even do experiments involving proofs, etc., but these experiments
 have no effect on the ongoing proof attempt.</p>

 <p>There are however exceptions to this loss of state when exiting a break.
 One exception pertains to iprinting (see @(see set-iprint)).  When iprinting
 is enabled in a break, it nevertheless is again disabled upon exiting the
 break.  However, the association of values with iprint indices persists even
 after exiting the break; that is, you can still obtain their values, and if
 you re-enable iprinting then indices will be generated from where they left
 off rather than returning to index 1.  The other exception pertains to setting
 the @(tsee brr-evisc-tuple) while inside break-rewrite: the effects persist.
 See @(tsee set-brr-evisc-tuple).</p>

 <p>When you enter break-rewrite a simple herald is printed such as:</p>

 @({
  (3 Breaking (:rewrite lemma12) on (delta a (+ 1 j)):
 })

 <p>The integer after the open parenthesis indicates the depth of nested
 break-rewrite calls.  In this discussion we use @('3') consistently for this
 integer.  Unless you abort or somehow enter unbalanced parentheses into the
 script, the entire session at a given depth will be enclosed in balanced
 parentheses, making it easy to skip over them in Emacs.</p>

 <p>You then will see the break-rewrite @(see prompt):</p>

 @({
  3 ACL2 !>
 })

 <p>The leading integer is, again, the depth.  Because breaks often occur
 recursively it is convenient always to know the level with which you are
 interacting.</p>

 <p>You may type arbitrary commands as in the top-level ACL2 loop.  For
 example, you might type:</p>

 @({
  3 ACL2 !>:help
 })

 <p>or</p>

 @({
  3 ACL2 !>:pe lemma12
 })

 <p>Exceptions are that @(':')@(tsee ubt) and related commands such as
 @(':')@(tsee ubu), as well as @(tsee puff) and @(tsee puff*), are only allowed
 to touch @(see command)s issued after entering the interactive break.
 (Technical detail: that is because @(tsee disable-ubt) is invoked when
 entering the break.)</p>

 <p>More likely than typing a history command, upon entering break-rewrite you
 will determine the context of the attempted application.  Here are some useful
 commands:</p>

 @({
  3 ACL2 >:target           ; the term being rewritten
  3 ACL2 >:unify-subst      ; the unifying substitution
  3 ACL2 >:path             ; the stack of goals pursued by the rewriter
                            ; starting at the top-level clause being simplified
                            ; and ending with the current application
 })

 <p>The output of the @(':path') command shows a stack of simplification and
 rewriting ``frames'' starting with the current top-level goal (in clausal form
 as a list of literals) and ending with the current target.  Frames should be
 self-explanatory.  Frames describing the attempt to apply a rewrite rule will
 display the name of the equivalence relation the rule uses (unless the
 relation is @('equal')).  All rewrite frames (including the attempt to apply a
 given rewrite rule) will display the current @(see geneqv) (the sense of
 equivalence the rewriter is obligated to maintain) unless the geneqv denotes
 just the @('equal')ity relation.</p>

 <p>At this point in the interaction the system has not yet tried to apply the
 @(see monitor)ed rule.  That is, it has not tried to establish the hypotheses,
 considered the heuristic cost of backchaining, rewritten the right-hand side
 of the conclusion, etc.  When you are ready for it to try the rule you can
 type one of several different ``proceed'' commands.  The basic proceed
 commands are @(':ok'), @(':go'), and @(':eval').</p>

 @({
  :ok
 })

 <p>exits break-rewrite without further interaction at the current depth.  When
 break-rewrite exits it prints ``@('3)')'' (actually, of course, the current
 depth!), closing the parenthesis that opened the current depth, @('3'),
 interaction.  However, between your typing the @(':ok') command and the exit
 from depth @('3') you may well see deeper break-rewrite breaks &mdash;
 triggered by any of your monitored runes &mdash; as the rewriter tries to
 apply the lemma that prompted the current depth @('3') break.</p>

 @({
  :go
 })

 <p>exits break-rewrite without further interaction at the current depth, but
 as it exits it prints out the result of the application attempt, i.e., whether
 the application succeeded, if so, what the @(':target') term was rewritten to,
 and if not why the rule was not applicable.</p>

 @({
  :eval
 })

 <p>causes break-rewrite to attempt to apply the rule but interaction at this
 depth of break-rewrite resumes when the attempt is complete.  When control
 returns to this level of break-rewrite a message indicating the result of the
 application attempt (just as in @(':go')) is printed, followed by the @(see
 prompt) for additional user input for the current depth @('3').</p>

 <p>Generally speaking, @(':ok') and @(':go') are used when the break in
 question is routine or uninteresting and @(':eval') is used when the break is
 one that the user anticipates is causing trouble.  For example, if you are
 trying to determine why a lemma isn't being applied to a given term and the
 @(':target') of the current break-rewrite is the term in question, you would
 usually @(':eval') the rule and if break-rewrite reports that the rule failed
 then you are in a position to determine why, for example by carefully
 inspecting the @(':')@(tsee type-alist) and perhaps the @(see
 linear-arithmetic) @(':pot-list') of governing assumptions or why some
 hypothesis of the rule could not be established.</p>

 <p>It is often the case that when you are in break-rewrite you wish to change
 the set of @(see monitor)ed @(see rune)s.  This can be done by using
 @(':')@(tsee monitor) and @(':')@(tsee unmonitor) as noted above.  For
 example, you might want to @(see monitor) a certain rule, say
 @('hyp-reliever'), just when it is being used while attempting to apply
 another rule, say @('main-lemma').  Typically then you would @(see monitor)
 @('main-lemma') at the ACL2 top-level, start the proof-attempt, and then in
 the break-rewrite in which @('main-lemma') is about to be tried, you would
 install a @(see monitor) on @('hyp-reliever').  If you then @(':eval') and get
 a break on @('hyp-reliever') you will know it is being used under the attempt
 to apply @('main-lemma').</p>

 <p>However, when the rewriter leaves this attempt to apply @('main-lemma'),
 @('hyp-reliever') will no longer be monitored.  That is, the list of monitored
 runes is maintained as a local variable of break-rewrite.  See @(tsee
 monitored-runes).</p>

 <p>@(':Ok!'), @(':go!'), and @(':eval!') are just like their counterparts
 (@(':ok'), @(':go'), and @(':eval'), respectively), except that before
 proceeding they unmonitor all runes.  Of course, this is only done in the
 scope of the interactive break in which these commands were used.  When
 control returns to the top-level of the ACL2 loop the monitored runes will
 have reverted to its original value there.  These commands allow you to
 proceed from the current depth without getting any deeper breaks.</p>

 <p>@(':Ok$'), @(':go$'), and @(':eval$') are similar but take an additional
 argument which must be a list of runic designators (or a single designator).
 See @(see rune).  Two examples the use of @(':eval$') are</p>

 @({
  3 ACL2 !>:eval$ hyp-reliever
 })

 <p>and</p>

 @({
  3 ACL2 !>:eval$ (hyp-reliever (:definition foo))
 })

 <p>The second command above is exactly equivalent to</p>

 @({
  3 ACL2 !>:monitor hyp-reliever t
  3 ACL2 !>:monitor (:definition foo) t
  3 ACL2 !>:eval
 })

 <p>Analogous remarks apply to @(':go$') and @(':ok$').  If you want to specify
 more sophisticated break criteria (rather than just @(':condition t')) you
 must use the @(':monitor') command explicitly before proceeding.</p>

 <p>Thus, there are nine ways to proceed from the initial entry into
 break-rewrite although we often speak as though there are two, @(':ok') and
 @(':eval'), and leave the others implicit.  We group @(':go') with @(':ok')
 because in all their flavors they exit break-rewrite without further
 interaction (at the current depth).  All the flavors of @(':eval') require
 further interaction after the rule has been tried.</p>

 <p>You are not permitted to &ldquo;re-@(':eval')&rdquo; a rule.  That is,
 after issuing the @(':eval') command in a given break, you cannot issue it
 again in that break.  The rule has been evaluated, the results are available
 to you, and that's that!  All you can do, aside from inspecting the context,
 is allow rewrite to continue, by issuing an @(':ok') or @(':go'), or
 abort.</p>

 <p>To abort a proof attempt and return to the top-level of ACL2 you may at any
 time type @('(a!)') followed by a carriage return or, equivalently (if you are
 not in a raw Lisp break) use the keyword command @(':a!').  See @(see a!).</p>

 <p>We now address ourselves to the post-@(':eval') interaction with
 break-rewrite.  As noted, post-@(':eval') interaction begins with
 break-rewrite's report on the results of applying the rule: whether it worked
 and either what it produced or why it failed.  This information is also
 printed by certain keyword commands available after @(':eval'), namely
 @(':wonp'), @(':rewritten-rhs') or (for @(see linear) rules) @(':poly-list'),
 and @(':failure-reason').  In addition, by using @(tsee brr@) you can obtain
 this information in the form of ACL2 data objects.  This allows the
 development of more sophisticated ``break conditions'' that test the context
 of the pending break and that return a list of commands to execute if a break
 occurs; see @(see monitor) for examples.  In this connection we point out the
 macro form @('(ok-if term)').  See @(see ok-if).  This command exits
 break-rewrite if @('term') evaluates to non-@('nil') and otherwise does not
 exit.  Thus it is possible to define macros that provide other kinds of exits
 from break-rewrite.  The only way to exit break-rewrite after @(':eval') is
 @(':ok') or @(':go') or the use of @(tsee ok-if).</p>

 <p>Note that when inside break-rewrite, all @(see history) commands, such as
 @(':')@(tsee pe), show the @(see enable)d status of rules with respect to the
 current point in the proof attempt.  For example, if you break while the
 prover is working on Subgoal 3, and the @(see hints) supplied for the proof
 specify @('("Subgoal 3" :in-theory (disable foo))') for some rule @('foo'),
 then @(':')@(tsee pe) will indicate that @('foo') is @(see disable)d: even
 though @('foo') may be enabled globally, it is shown as disabled because it is
 disabled during Subgoal 3.  See subtopics of @(see history) for a list of all
 such history commands.  In addition to those commands, the function @(tsee
 disabledp) is also evaluated inside break-rewrite with respect to the current
 enabled state of the prover.</p>

 <p>We have not discussed &ldquo;near-miss&rdquo; breaks.  These are caused
 when a monitored rune specifies one of the near-miss break criteria and the
 rune's pattern fails to match the target but &ldquo;almost&rdquo; matches
 according to the criteria.  See @(tsee monitor) for a discussion of near-miss
 break criteria.  But for example, if @('main-lemma') rewrites the term
 @('(f (g (h x) y) x)') and you've installed a monitor on it like this:</p>

 @({
 :monitor main-lemma (:abstraction (f (g u v) w))
 })

 <p>then if the rewriter encountered the target term @('(F (G (MUMBLE A) B)
 C)') it would cause a near-miss break because the pattern of @('main-lemma')
 does not match the target but the specified abstraction of the pattern does
 match the target.</p>

 <p>You interact with a near-miss break just like the breaks described above,
 except some commands (e.g., @(':eval')) are unavailable because the rule did
 not match and thus there is no way to proceed except to exit the break and try
 the next lemma.</p>

 <p>The rest of this @(see documentation) discusses a few implementation
 details of break-rewrite and may not be interesting to the typical user.</p>

 <p>There is no ACL2 function named break-rewrite &mdash; which is why we don't
 write it in typewriter font in this documentation.  Break-rewrite is an
 illusion created by appropriate calls to three ``break point handlers'' named
 @('near-miss-brkpt1'), @('brkpt1') and @('brkpt2').  As previously noted,
 break-rewrite is @(tsee ld) operating on a @(see wormhole) @(see state).  One
 might therefore wonder how break-rewrite can apply a rule and then communicate
 the results back to the rewriter running in the external @(see state).  The
 answer is that it cannot.  Nothing can be communicated through a @(see
 wormhole).  In fact, the break point handlers are each calls of @(tsee ld)
 running on @(see wormhole) @(see state)s.  They maintain a state machine
 inside the wormhole.  For example, @('brkpt1') is called by rewrite after a
 successful match, if the monitored @(':condition') is true, an interactive
 break occurs.  Upon an @(':ok') or @(':eval'), the wormhole's status
 information is updated, the wormhole is exited (losing any state changes made
 inside the wormhole), rewrite continues to do whatever rewrite does for that
 lemma, and then @('brkpt2') is called.  @('Brkpt2') then uses the state
 information in the wormhole to decide whether to interact or not.</p>

 <p>This helps explain why the rewriter behaves more sluggishly when @('(brr
 t)') has been done: it is entering and exiting wormholes to figure out whether
 to trigger an interactive break.  When you are through with break-rewrite, we
 recommend @('(brr nil)').</p>

 <p>This design causes certain anomalies that might be troubling.</p>

 <p>Suppose you are inside a depth @('3') break before @(':evaling') a
 rule (i.e., you're in the @('brkpt1') @(see wormhole) @(see state)) you define
 some function, @('foo').  Suppose then you @(':eval') the rule and eventually
 control returns to the depth @('3') break (i.e., now you're in the @('brkpt2')
 @(see wormhole) @(see state) with the results of the application in it).  You
 will discover that @('foo') is no longer defined!  That is because the @(see
 wormhole) @(see state) created during your pre-@(':eval') interaction is lost
 when we exit the @(see wormhole) to resume the proof attempt.  The
 post-@(':eval') @(see wormhole) @(see state) is in fact identical to the
 initial pre-@(':eval') @(see state) (except for the results of the
 application) because @(tsee rewrite) did not change the external @(see state)
 and both @(see wormhole) @(see state)s are copies of it.  A similar issue
 occurs with the use of @(see trace) utilities: all effects of calling @(tsee
 trace$) and @(tsee untrace$) are erased when you proceed from a break in the
 break-rewrite loop.</p>

 <p>See the subtopics listed below to learn more about
 @('break-rewrite').</p>")

(defxdoc breaks
  :parents (errors)
  :short "Common Lisp breaks"
  :long "@({
  Example:
  Broken at PROVE.  Type :H for Help.
  >>:Q

  ACL2 !>
 })

 <p>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''.</p>

 <p>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 @(see prompt)s 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.</p>

 <p>For ACL2 built on most host Common Lisps, you can expect to see a different
 prompt at the break than you would see in the ACL2 read-eval-print loop.  See
 @(see prompt) for how to change the raw Lisp prompt to emphasize that one is
 in raw Lisp, and hence may wish to quit from the break.</p>

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

 <p>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 @(tsee 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.</p>")

(defxdoc broken-link
  :parents (documentation)
  :short "Placeholder for link to documentation that resides in the community
 books"
  :long "<p>You may have attempted to access information about the ACL2 @(see
 community-books) while looking at the ACL2 User's Manual, which contains @(see
 documentation) only about the ACL2 <i>system</i>, and does not include
 documentation from the @(see community-books).  Please point your browser at
 the @(`(:raw (combined-manual-ref))`) (or if browsing in @(see ACL2-Doc),
 switch to that manual with meta-0 I) to access the desired topic.</p>

 <p>If you want information about the book where your missing topic is defined,
 see @(see broken-link-table).</p>")

(defxdoc broken-link-table
  :parents (broken-link)
  :short "Map @(see documentation) topics to the community books that define
 them"
  :long "<p>The table below maps topics to book locations that reside only in
 the ACL2+Books combined manual, not the ACL2 User's Manual.  For example, the
 entry</p>

 @({
 (b* "[books]/std/util/bstar.lisp")
 })

 <p>signifies that the topic @('B*') is documented in the community
 book @('std/util/bstar.lisp').</p>

 <p>@(`(:code *acl2-broken-links-alist*)`)</p>")

(defxdoc brr
  :parents (break-rewrite)
  :short "To enable or disable the breaking of rewrite rules"
  :long "@({
  Example:
  :brr t       ; enable
  (brr t)      ; enable (same as above)
  (brr t t)    ; enable with less output (rarely invoked interactively)
  :brr nil     ; disable

  General Form:
  (brr flg &optional quietp)
 })

 <p>where @('flg') and the optional @('quietp') argument evaluate to @('t') or
 @('nil').  This function modifies @(tsee state) so that the attempted
 application of certain rewrite rules are ``broken.'' ``@('Brr')'' stands for
 ``break-rewrite'' and can be thought of as a mode with two settings.  The
 normal mode is ``disabled.''</p>

 <p>For a more thorough introduction to the break rewrite system see @(see
 break-rewrite).  For a related proof debugging utility see @(see
 with-brr-data).</p>

 <p>When @('brr') mode is ``enabled'' the ACL2 rewriter monitors the attempts
 to apply certain rules and advises the user of those attempts by entering an
 interactive wormhole break.  From within this break the user can watch
 selected application attempts.  The user can also interact with the system
 during @('brr') breaks via @(tsee brr-commands).</p>

 <p>The rules monitored are selected by using the @(tsee monitor) and @(tsee
 unmonitor) commands.  It is possible to break a rune ``conditionally'' in the
 sense that an interactive break will occur only if a specified predicate is
 true of the environment at the time of the attempted application.  See @(see
 monitor) and see @(see unmonitor).</p>

 <p>Even if a non-empty set of rules has been selected, no breaks will occur
 unless @('brr') mode is enabled.  Thus, the first time in a session that you
 wish to monitor a rewrite rule, use @(':brr') @('t') to enable @('brr') mode.
 Thereafter you may select runes to be monitored with @(tsee monitor) and
 @(tsee unmonitor) with the effect that whenever monitored rules are tried (and
 their break conditions are met) an interactive break will occur.  Be advised
 that when @('brr') mode is enabled the rewriter is somewhat slower than
 normal.  Furthermore, that sluggishness persists even if no runes are
 monitored.  You may regain normal performance &mdash; regardless of what runes
 are monitored &mdash; by disabling @('brr') mode with @(':brr') @('nil').</p>

 <p>Why isn't @('brr') mode disabled automatically when no runes are monitored?
 More generally, why does ACL2 have @('brr') mode at all?  Why not just test
 whether there are monitored runes?  If you care about the answers, see @(see
 why-brr).</p>

 <p>BRR Mode, Console Interrupts, and Subsidiary Prover Calls: If the system is
 operating in @('brr') mode and you break into raw Lisp (as by causing a
 console interrupt or happening upon a signaled Lisp error; see @(see breaks)),
 you can return to the ACL2 top-level, outside any break-rewrite environment,
 by executing @('(')@(tsee abort!)@(')').  Otherwise, the normal way to quit
 from such a raw Lisp break (for example @(':q') in GCL, @(':reset') in Allegro
 CL, and @('q') in CMU CL) will return to the innermost ACL2 read-eval-print
 loop, which may or may not be the top-level of your ACL2 session!  In
 particular, if the interrupt or error break happens to occur while ACL2 is
 within a break-rewrite break (in which it is preparing to read @(tsee
 brr-commands)), the abort will merely return to break-rewrite break.  Upon
 exiting that environment, normal theorem proving is continued (and the
 break-rewrite breaks may be entered again in response to subsequent monitored
 rule applications).  In addition, if while in a break-rewrite break, say at
 depth @('d'), you invoke the theorem prover recursively as by typing a @(tsee
 thm) or @(tsee defthm) or @(tsee defun) command to break-rewrite, recursive
 breaks may occur with depths starting at @('d+1').  This can get confusing
 because it may appear that the ongoing (sub-)proofs are part of the original
 proof when in fact the system is just carrying out your commands.</p>")

(defxdoc brr-commands
  :parents (break-rewrite)
  :short "@(see Break-Rewrite) Commands"
  :long "<p>Below is a list of commonly used @(see break-rewrite) keyword
  commands.  These are only defined within the breaks caused by @(tsee
  monitor)s on runes in the process of being considered by the ACL2 rewriter.
  These breaks interact with you from within a @(tsee wormhole) and are handled
  by @(tsee ld) (the same function that manages ACL2's top-level interactive
  read-eval-print loop).  So within certain limitations imposed by wormholes,
  you can evaluate any command you would at the top-level of ACL2 in addition
  to the special commands below.</p>

  <p>Many break commands display terms, e.g., the target being rewritten, and
  &ldquo;large&rdquo; terms are &ldquo;eviscerated&rdquo; (i.e., abbreviated)
  before printing.  These commands have corresponding commands suffixed with a
  ``+'' that avoid evisceration so that the terms in question are printed in
  full.  See @(see brr-evisc-tuple).  The notation ``@(':ancestors[+]')'' below
  indicates that the @(':ancestors') command may print abbreviate terms but the
  @(':ancestors+') command does not.</p>

 @({
 :a!                abort to ACL2 top-level
 :ancestors[+]      negations of backchaining hypotheses being pursued
 :btm[+]            bottom-most frame in :path
 :eval              try the rule (i.e., recursively try to relieve
                      the hypotheses and other conditions, possibly
                      producing other breaks) and return to this
                      break afterwards so you can query results
 :eval!             :eval but remove all monitors first (see below)
 :eval$ runes       :eval but first add monitors for runes (see below)
 :explain-near-miss[+]
                    print an explanation of why the rule's pattern failed
                      to match the :target; only relevant in a break caused
                      by a near miss
 :failure-reason[+] reason rule failed (after :eval)
 :final-ttree[+]    ttree after :eval (see :DOC ttree)
 :frame[+] i        ith frame in :path
 :geneqv[+]         generated equivalence relation to be maintained
 :go                :eval but don't return to this break, just
                      print the result of the try
 :go!               :go but first remove all monitors (see below)
 :go$ runes         :go but first add monitors for runes (see below)
 :help              this message
 :hyp i             ith hypothesis of the rule
 :hyps              hypotheses of the rule
 :initial-ttree[+]  ttree before :eval (see :DOC ttree)
 :lhs[+]            left-hand side of rule's conclusion (or, in the case
                      of :rewrite-quoted-constant rules of form [2], the
                      right-hand side!); this is the pattern that the
                      target must match for this :rewrite rule to fire
 :max-term[+]       maximal term of a :linear lemma; this is the pattern
                      that the target must match for this :linear rule to
                      fire
 :ok                like :go, but don't print the result of the try
 :ok!               :ok but first remove all monitors (see below)
 :ok$ runes         :ok but first add monitors for runes (see below)
 :path[+]           rewriter's path from top clause to :target
 :poly-list[+]      list of polynomials (after :eval) of a linear rule,
                      where the leading term of each is enclosed in an
                      extra set of parentheses
 :pot-list[+]       set of polynomials governing :target,
                      organized by maximal term
 :rewritten-rhs[+]  rewritten :rhs (after :eval) of a rewrite rule
 :rhs               right-hand side of rule's conclusion (or, in the case
                      of :rewrite-quoted-constant rules of form [2], the
                      left-hand side!)
 :standard-help     :help message from ACL2 top-level
 :target[+]         term being rewritten
 :top[+]            top-most frame in :path
 :type-alist[+]     type assumptions governing :target
 :unify-subst[+]    substitution making :lhs equal :target
 :wonp              indicates whether application succeeded (after :eval)
 })

 <p>The form @('(')@(tsee brr@)@(' :cmd)'), when evaluated within a break,
 will return the value that is only printed by certain of the keyword commands
 above.  This is particularly useful when programming break conditions.  See
 @(tsee monitor).</p>

 <p>Since you're actually in a general read-eval-print loop when interacting
 with @(see break-rewrite) you may type the usual ACL2 commands like
 @(':')@(tsee pbt) or @(':')@(tsee pe) or even @(tsee defun) and @(tsee
 defthm).  You cannot modify @(see stobj)s or files from within the break.
 However, all @(see state) changes you cause from within @(see break-rewrite)
 are lost when you exit or @(':eval') the rule.</p>

 <p>Note that if you are breaking on a @(see monitor)ed @(see linear) rule,
 several of the commands listed above do not apply: @(':lhs'), @(':rhs'),
 @(':initial-ttree'), and @(':final-ttree').  The pattern used to fire a linear
 rule is found with the command @(':max-term').  In addition,
 @(':rewritten-rhs') also does not apply to linear rules, but instead,
 @(':poly-list') shows the result of applying the linear lemma as a list of
 polynomials, implicitly conjoined.  The leading term of each polynomial is
 enclosed in an extra set of parentheses.</p>

 <p>See the discussion of form [2] @(':')@(tsee rewrite-quoted-constant) rules
 for an explanation of the swapped meanings of ``@(':lhs')'' and
 ``@(':rhs').''</p>

 <p>The commands @(':eval$'), @(':go$'), and @(':ok$') take an argument, called
 runes, which may be a list of runes and/or runic designators (see @(see rune))
 or a single rune or runic designator.  For each rune in runes, these commands
 execute @(':')@(tsee monitor) rune @('t'), and then execute @(':eval'),
 @(':go') or @(':ok') as appropriate.</p>

 <p>This is useful if you want to monitor the use of a &ldquo;secondary&rdquo;
 rune only during the attempt to apply a &ldquo;primary&rdquo; rune: install
 the monitor on the secondary rune inside the break caused by the primary rune.
 In the case of @(':eval$'), when the attempt to apply the primary rune is
 finished you will be back in the interactive break and can inspect the
 results.  You will notice that the secondary rune is still on the list of
 @(tsee monitored-runes).  However, when you exit that break
 @('monitored-runes') will be restored to its earlier value.  In the case of
 @('go$') and @('ok$'), no interactive break occurs after the primary rune has
 been applied.</p>

 <p>Similar remarks apply to @(':eval!'), @(':go!'), and @(':ok!') except they
 first @(':')@(tsee unmonitor) @(':all'), before proceeding with the
 appropriate @(':eval'), @(':go'), or @(':ok').  These commands are useful if
 you want no breaks to occur while attempting to apply the rune that caused the
 current break.</p>

 <p>Recall (from the discussion of @(tsee monitor)s) that break conditions
 terms installed as part of break criteria do not just determine whether a
 break occurs but can compute the initial break commands fed to the interactive
 loop.  Thus, for example, you can install a monitor that causes the rewriter
 to not only break when a certain rune is used, but then automatically print
 information, proceed from the break, inspect the result, and then either exit
 the break or prompt for user input.  See the discussion in @(tsee
 monitor).</p>

 <p>Note: If you use commands that change the monitored runes during a break,
 e.g., @(tsee monitor), @(tsee unmonitor), or @(':eval!'), @(':eval$'), etc.,
 then abort during the recursion, the list of monitored runes will not
 necessarily be restored to its original top-level setting.</p>")

(defxdoc brr-evisc-tuple
  :parents (brr evisc-tuple)
  :short "Determines partial suppression of output from @(see brr-commands)"
  :long "<p>See @(see evisc-tuple) for relevant background on ``evisceration'':
 eliding of subexpressions during printing.  Also see @(see break-rewrite) for
 background on the break-rewrite loop.</p>

 @({
 General Form:
 (brr-evisc-tuple state)
 })

 <p>The value of this function is used as the evisceration tuple by @(see
 brr-commands).  The value can be changed with @(tsee set-brr-evisc-tuple) or
 the more general @(tsee set-evisc-tuple).</p>

 <p>A special value, @(':default'), is legal for this evisc-tuple, and is its
 initial value.  In that case the actual evisc-tuple used during output from
 @(see brr-commands) &mdash; which we call the <i>effective value</i> of the
 @('brr-evisc-tuple') &mdash; is the value of the evisc-tuple for terms.  See
 @(see set-evisc-tuple), in particular, the discussion of the @(':term') site
 for setting evisc-tuples.</p>

 <p>Think of @('brr-evisc-tuple') as a true global variable, not a locally
 bound variable of break-rewrite.  In particular, if you set the
 @('brr-evisc-tuple') inside a break-rewrite interactive break and eventually
 exit that break &mdash; either to enter a deeper break or return to a
 shallower break or to the ACL2 top-level &mdash; the @('brr-evisc-tuple') will
 retain its chronologically most recent setting.</p>

 <p>The @('brr-evisc-tuple') is used when @(see break-rewrite) prints its
 banner opening or closing a break on some monitored rune and when certain
 @(see brr-commands) print their results.</p>

 <p>When you're in a break-rewrite break, you're actually dealing with the
 read-eval-print loop managed by @(tsee ld).  It prints its results using the
 @(tsee ld-evisc-tuple), while @(tsee brr-commands) use @('brr-evisc-tuple').
 This can cause some confusion.</p>

 <p>For example, suppose you have set the @('brr-evisc-tuple') to
 @('(evisc-tuple 2 3 nil nil)') so break-rewrite banners and brr-commands only
 print to depth 2 and length 3.  Suppose the target term is @('(F (G (H 1)) 2 3
 4 5 6 7)').  Then the following interaction with break-rewrite could
 occur:</p>

 @({
 3 ACL2 >:target
 (F (G #) 2 ...)
 3 ACL2 >(make-list 10)
 (NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL)
 })

 <p>You might ask ``Given that the @('brr-evisc-tuple') limits the print length
 to @('3'), which I see when I print @(':target'), how come the @('make-list')
 showed all 10 elements?''  The answer is that the @('brr-command')
 @(':target') actually printed the target with the @('brr-evisc-tuple') and
 returned @('(value :invisible)') which @('ld')'s read-eval-print loop doesn't
 print.  But the @('make-list') returned a list of length ten and the
 read-eval-print loop printed it using the @(tsee ld-evisc-tuple).</p>

 <p>Another issue relating @('brr-evisc-tuple') and @('ld-evisc-tuple') is that
 while @('brr-evisc-tuple') is a true global, retaining its chronologically
 most recently set value at all depths of break-rewrite, @('ld-evisc-tuple') is
 locally bound by break-rewrite (actually, by the @('ld') in @('wormhole')) and
 so sees its value restored as break-rewrite ascends back toward the top-level
 of ACL2.</p>")

(defxdoc brr-near-missp
  :parents (break-rewrite)
  :short "attachable function for determining “near misses”"
  :long "<p>This is a system function that determine whether a failed match of
  a monitored rule constitutes a near miss.</p>

  <p><b>Note:</b>This function is attachable (see @(see defattach)).</p>

  @({
  General Form:
  (brr-near-missp msgp lemma target rcnst criteria-alist)
  })

  <p>where msgp is @('t') or @('nil'), @('lemma') is the ACL2 record
  representing a @(tsee monitor)ed @(':rewrite') rule or @(':linear') rule,
  @('target') is a term to which the rewriter tried to apply the rule but
  failed to match the pattern in the lemma, @('rcnst') is the rewrite constant
  at the time of the attempt, and @('criteria-alist') is a symbol-alist
  associated with the rule in @(tsee monitored-runes).</p>

  <p>The function determines whether the pattern of the lemma
  &ldquo;almost&rdquo; matches the target, i.e., whether a &ldquo;near
  miss&rdquo; has occurred.  The function is only called if the exact match
  failed.  The built-in version of this function checks the criteria described
  in @(tsee monitor).  If a near miss has occurred, the result is either @('t')
  or a message (see @(tsee msg)) object describing the near miss.  If a near
  miss did not occur, the result is @('nil').  See the source code for
  @('built-in-brr-near-missp') for details of how the built-in version of this
  function operates.</p>")

(defxdoc brr@
  :parents (break-rewrite)
  :short "To access context sensitive information within @(tsee break-rewrite)"
  :long "@({
  Example:
  (brr@ :target)      ; the term being rewritten
  (brr@ :unify-subst) ; the unifying substitution

  General Form:
  (brr@ :symbol)
 })

 <p>where @(':symbol') is one of the keywords displayed below.  This utility
 may be most useful for system hackers; see @(see brr-commands) for queries
 that are more at a user level.  In particular, keywords marked below with
 @('*') probably require an implementor's knowledge of the system to use
 effectively.  They are supported but not well documented.  More is said on
 this topic following the table.  For background on the notion of
 ``translated'' term, see @(see term).</p>

 @({
  :symbol             (brr@ :symbol)
  -------             ---------------------

  :target             the term to be rewritten.  This term is an
                      instantiation of the left-hand side of the
                      conclusion of the rewrite-rule being broken.
                      This term is in translated form!  Thus, if
                      you are expecting (equal x nil) -- and your
                      expectation is almost right -- you will see
                      (equal x 'nil); similarly, instead of (cadr a)
                      you will see (car (cdr a)).  In translated
                      forms, all constants are quoted (even nil, t,
                      strings and numbers) and all macros are
                      expanded.

  :unify-subst        the substitution that, when applied to :target,
                      produces the left-hand side of the rule being
                      broken.  This substitution is an alist pairing
                      variable symbols to translated (!) terms.

  :wonp               t or nil indicating whether the rune was
                      successfully applied.  (brr@ :wonp) returns
                      nil if evaluated before :EVALing the rule.

  :rewritten-rhs      the result of successfully applying the rewrite
                      rule or else nil if (brr@ :wonp) is nil.  The
                      result of successfully applying the rule is
                      always a translated (!) term and is never nil.

  :poly-list          the result of successfully applying the linear
                      rule or else nil if (brr@ :wonp) is nil.  This
                      result represents the list of polynomials
                      produced by the rule application.  The leading
                      term of each polynomial is enclosed in an extra
                      set of parentheses.

  :pot-list        *  the pot-list, which is the set of polynomials
                      that are assumed in the current context,
                      organized by maximal term.  Each polynomial in
                      the list is a linear-pot record.

  :failure-reason     some non-nil lisp object indicating why the rule
                      was not applied or else nil.  Before the rule is
                      :EVALed, (brr@ :failure-reason) is nil.  After
                      :EVALing the rule, (brr@ :failure-reason) is nil
                      if (brr@ :wonp) is t.  Rather than document the
                      various non-nil objects returned as the failure
                      reason, we encourage you simply to evaluate
                      (brr@ :failure-reason) in the contexts of interest.
                      Alternatively, study the ACL2 function tilde-@-
                      failure-reason-phrase.

  :lemma           *  the rewrite rule being broken.  For example,
                      (access rewrite-rule (brr@ :lemma) :lhs) will
                      return the left-hand side of the conclusion
                      of the rule.

  :type-alist      *  a display of the type-alist governing :target.
                      Elements on the displayed list are of the form
                      (term type), where term is a term and type
                      describes information about term assumed to hold in
                      the current context.  (See also the documentation for
                      type-alist.)  The type-alist may be used to determine
                      the current assumptions, e.g., whether A is a CONSP.

  :geneqv          *  the generated equivalence relation that specifies
                      what equivalence relations may be used to rewrite
                      the target.  (See the documentation for geneqv and
                      refinement-failure.)

  :ancestors       *  a stack of frames indicating the backchain history
                      of the current context.  The theorem prover is in
                      the process of trying to establish each hypothesis
                      in this stack.  Thus, the negation of each hypothesis
                      can be assumed false.  Each frame also records the
                      rules on behalf of which this backchaining is being
                      done and the weight (function symbol count) of the
                      hypothesis.  All three items are involved in the
                      heuristic for preventing infinite backchaining.
                      Exception:  Some frames are ``binding hypotheses''
                      (equal var term) or (equiv var (double-rewrite term))
                      that bind variable var to the result of rewriting
                      term.  The ACL2 source code has a definition
                      (defrec ancestor ...) that may provide some relevant
                      insight.

  :initial-ttree   *  the initial and (after :EVAL) final tag trees,
  :final-ttree        respectively.  (Tag trees are low-level data structures
                      that store lemmas used and other information, as
                      documented in topic TTREE.)

  :gstack          *  the current goal stack.  The gstack is maintained
                      by rewrite and is the data structure printed as the
                      current ``path.''  Thus, any information derivable
                      from the :path brr command is derivable from gstack.
                      For example, from gstack one might determine that
                      the current term is the second hypothesis of a
                      certain rewrite rule.
 })

 <p>In general @('brr@-expressions') are used in break conditions, the
 expressions that determine whether interactive breaks occur when @(see
 monitor)ed @(see rune)s are applied.  See @(see monitor).  For example, you
 might want to break only those attempts in which one particular term is being
 rewritten or only those attempts in which the binding for the variable @('a')
 is known to be a @(tsee consp).  Such conditions can be expressed using ACL2
 system functions and the information provided by @('brr@').  Unfortunately,
 digging some of this information out of the internal data structures may be
 awkward or may, at least, require intimate knowledge of the system functions.
 But since conditional expressions may employ arbitrary functions and macros,
 we anticipate that a set of convenient primitives will gradually evolve within
 the ACL2 community.  It is to encourage this evolution that @('brr@') provides
 access to the @('*')'d data.</p>")

(defxdoc built-in-clause
  :parents (rule-classes)
  :short "To build a @(see clause) into the simplifier"
  :long "<p>See @(see rule-classes) for a general discussion of rule classes,
 including how they are used to build rules from formulas and a discussion of
 the various keywords in a rule class description.</p>

 @({
  Example:
  (defthm acl2-count-abl
    (and (implies (and (true-listp x)
                       (not (equal x nil)))
                  (< (acl2-count (abl x))
                     (acl2-count x)))
         (implies (and (true-listp x)
                       (not (equal nil x)))
                  (< (acl2-count (abl x))
                     (acl2-count x))))
    :rule-classes :built-in-clause)
 })

 <p>A @(':built-in-clause') rule can be built from any formula other than
 propositional tautologies.  Roughly speaking, the system uses the list of
 built-in @(see clause)s as the first method of proof when attacking a new
 goal.  Any goal that is subsumed by a built in clause is proved
 ``silently.''</p>

 <p>ACL2 maintains a set of ``built-in'' clauses that are used to short-circuit
 certain theorem proving tasks.  We discuss this at length below.  When a
 theorem is given the rule class @(':built-in-clause') ACL2 flattens the @(tsee
 implies) and @(tsee and) structure of the @(':')@(tsee corollary) formula so
 as to obtain a set of formulas whose conjunction is equivalent to the given
 corollary.  It then converts each of these to clausal form and adds each
 clause to the set of built-in clauses.</p>

 <p>The example above (regardless of the definition of @('abl')) will build in
 two clauses,</p>

 @({
  {(not (true-listp x))
   (equal x nil)
   (< (acl2-count (abl x)) (acl2-count x))}
 })

 <p>and</p>

 @({
  {(not (true-listp x))
   (equal nil x)
   (< (acl2-count (abl x)) (acl2-count x))}.
 })

 <p>We now give more background.</p>

 <p>Recall that a clause is a set of terms, implicitly representing the
 disjunction of the terms.  Clause @('c1') is ``subsumed'' by clause @('c2') if
 some instance of @('c2') is a subset @('c1').</p>

 <p>For example, let @('c1') be</p>

 @({
  {(not (consp l))
   (equal a (car l))
   (< (acl2-count (cdr l)) (acl2-count l))}.
 })

 <p>Then @('c1') is subsumed by @('c2'), shown below,</p>

 @({
  {(not (consp x))
   ; second term omitted here
   (< (acl2-count (cdr x)) (acl2-count x))}
 })

 <p>because we can instantiate @('x') in @('c2') with @('l') to obtain a subset
 of @('c1').</p>

 <p>Observe that @('c1') is the clausal form of</p>

 @({
  (implies (and (consp l)
                (not (equal a (car l))))
           (< (acl2-count (cdr l)) (acl2-count l))),
 })

 <p>@('c2') is the clausal form of</p>

 @({
  (implies (consp l)
           (< (acl2-count (cdr l)) (acl2-count l)))
 })

 <p>and the subsumption property just means that @('c1') follows trivially from
 @('c2') by instantiation.</p>

 <p>The set of built-in clauses is just a set of known theorems in clausal
 form.  Any formula that is subsumed by a built-in clause is thus a theorem.
 If the set of built-in theorems is reasonably small, this little theorem
 prover is fast.  ACL2 uses the ``built-in clause check'' in four places: (1)
 at the top of the iteration in the prover &mdash; thus if a built-in clause is
 generated as a subgoal it will be recognized when that goal is considered, (2)
 within the simplifier so that no built-in clause is ever generated by
 simplification, (3) as a filter on the clauses generated to prove the
 termination of recursively @(tsee defun)'d functions and (4) as a filter on
 the clauses generated to verify the guards of a function.</p>

 <p>The latter two uses are the ones that most often motivate an extension to
 the set of built-in clauses.  Frequently a given formalization problem
 requires the definition of many functions which require virtually identical
 termination and/or guard proofs.  These proofs can be short-circuited by
 extending the set of built-in clauses to contain the most general forms of the
 clauses generated by the definitional schemes in use.</p>

 <p>The attentive user might have noticed that there are some recursive
 schemes, e.g., recursion by @(tsee cdr) after testing @(tsee consp), that ACL2
 just seems to ``know'' are ok, while for others it generates measure clauses
 to prove.  Actually, it always generates measure clauses but then filters out
 any that pass the built-in clause check.  When ACL2 is initialized, the clause
 justifying @(tsee cdr) recursion after a @(tsee consp) test is added to the
 set of built-in clauses.  (That clause is @('c2') above.)</p>

 <p>Note that only a subsumption check is made; no rewriting or simplification
 is done.  Thus, if we want the system to ``know'' that @(tsee cdr) recursion
 is ok after a negative @(tsee atom) test (which, by the definition of @(tsee
 atom), is the same as a @(tsee consp) test), we have to build in a second
 clause.  The subsumption algorithm does not ``know'' about commutative
 functions.  Thus, for predictability, we have built in commuted versions of
 each clause involving commutative functions.  For example, we build in
 both</p>

 @({
  {(not (integerp x))
   (< 0 x)
   (= x 0)
   (< (acl2-count (+ -1 x)) (acl2-count x))}
 })

 <p>and the commuted version</p>

 @({
  {(not (integerp x))
   (< 0 x)
   (= 0 x)
   (< (acl2-count (+ -1 x)) (acl2-count x))}
 })

 <p>so that the user need not worry whether to write @('(= x 0)') or @('(= 0
 x)') in definitions.</p>

 <p>@(':built-in-clause') rules added by the user can be enabled and
 disabled.</p>")

(defxdoc butlast
  :parents (lists acl2-built-ins)
  :short "All but a final segment of a list"
  :long "<p>@('(Butlast l n)') is the list obtained by removing the last @('n')
 elements from the true list @('l').  The following are theorems.</p>

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

  (equal (len (butlast l n)) (nfix (- (len l) (nfix n)))))
 })

 <p>For related functions, see @(see take) and see @(see nthcdr).</p>

 <p>The @(see guard) for @('(butlast l n)') requires that @('n') is a
 nonnegative integer and @('lst') is a true list.</p>

 <p>@('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.</p>

 @(def butlast)")

(defxdoc caaaar
  :parents (conses acl2-built-ins)
  :short "@(tsee car) of the @(tsee caaar)"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc caaadr
  :parents (conses acl2-built-ins)
  :short "@(tsee car) of the @(tsee caadr)"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc caaar
  :parents (conses acl2-built-ins)
  :short "@(tsee car) of the @(tsee caar)"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc caadar
  :parents (conses acl2-built-ins)
  :short "@(tsee car) of the @(tsee cadar)"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc caaddr
  :parents (conses acl2-built-ins)
  :short "@(tsee car) of the @(tsee caddr)"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc caadr
  :parents (conses acl2-built-ins)
  :short "@(tsee car) of the @(tsee cadr)"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc caar
  :parents (conses acl2-built-ins)
  :short "@(tsee car) of the @(tsee car)"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc cadaar
  :parents (conses acl2-built-ins)
  :short "@(tsee car) of the @(tsee cdaar)"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc cadadr
  :parents (conses acl2-built-ins)
  :short "@(tsee car) of the @(tsee cdadr)"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc cadar
  :parents (conses acl2-built-ins)
  :short "@(tsee car) of the @(tsee cdar)"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc caddar
  :parents (conses acl2-built-ins)
  :short "@(tsee car) of the @(tsee cddar)"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc cadddr
  :parents (conses acl2-built-ins)
  :short "@(tsee car) of the @(tsee cdddr)"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc caddr
  :parents (conses acl2-built-ins)
  :short "@(tsee car) of the @(tsee cddr)"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc cadr
  :parents (conses acl2-built-ins)
  :short "@(tsee car) of the @(tsee cdr)"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc calling-ld-in-bad-contexts
  :parents (ld)
  :short "Errors caused by calling @(tsee ld) in inappropriate contexts"
  :long "<p>The macro @(tsee ld) was designed to be called directly in the
 top-level ACL2 loop, although there may be a few occasions for calling it from
 functions.  ACL2 cannot cope with invocations of @(tsee ld) during the process
 of loading a compiled file for a book, so that is an error.</p>

 <p>Specifically: ACL2 will cause an error in the following two
 circumstances:</p>

 <ul>

 <li>when calling @(tsee ld) inside @(tsee progn!) unless state global
 @('ld-okp') is first set to @('t'), e.g., using @('(assign ld-okp t)');
 also,</li>

 <li>when calling @('ld') while inside raw Lisp, e.g., when loading a compiled
 file during an invocation of @(tsee include-book).</li>

 </ul>

 <p>Consider for example the following book, where file @('const.lsp') contains
 the single form @('(defconst *foo* '(a b))') after its initial @(tsee
 in-package) form.</p>

 @({
 (in-package "ACL2")
 (defttag t)
 (progn! (ld "const.lsp"))
 })

 <p>An attempt to certify this book as follows</p>

 @({
 (certify-book "const-wrapper" 0 t :ttags :all)
 })

 <p>will cause an error:</p>

 @({
 ACL2 Error in LD:  It is illegal to call LD in this context.  See :DOC
 calling-ld-in-bad-contexts.
 })

 <p>However, that error can be avoided by expanding the @(tsee progn!) call as
 follows.</p>

 @({
 (progn! (assign ld-okp t)
         (ld "const.lsp"))
 })

 <p>Now certification succeeds; however, any subsequent call of @(tsee
 include-book) will fail to load the compiled file for the book.  Again, that
 is necessary because of how ACL2 is designed; in this case, the @(tsee ld)
 call would interfere with tracking of constant definitions when loading the
 compiled file for the book.  To avoid warnings about loading compiled files,
 either certify the book without creating a compiled file or else include the
 book without loading the compiled file; see @(see certify-book) and @(see
 include-book).</p>

 <p>Note that it is legal to put a definition such as the following into a
 book, where @('ld') is called in the body of a function; the two conditions
 above do not prohibit this.</p>

 @({
 (defun foo (state)
   (declare (xargs :guard t :stobjs state :mode :program))
   (ld '((defun h (x) x)) :ld-user-stobjs-modified-warning t))
 })

 <p>One can then include the book, evaluate @('(foo state)'), and then evaluate
 calls of @('h').</p>")

(defxdoc canonical-pathname
  :parents (programming-with-state acl2-built-ins)
  :short "The true absolute filename, with soft links resolved"
  :long "<p>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').</p>

 <p>The specification of @('(canonical-pathname fname dir-p state)') when
 @('dir-p') is not @('nil') is similar, except that if the specified file
 exists but is not a directory, then the result is @('nil').</p>

 <p>The function @('canonical-pathname') has a guard of @('t'), though the
 second argument must be the ACL2 @(tsee state).  This function is introduced
 with the following properties.</p>

 @({
  (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)
 })

 <p>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.</p>")

(defxdoc car
  :parents (conses acl2-built-ins)
  :short "Returns the first element of a non-empty list, else @('nil')"
  :long "<p>Completion Axiom (@('completion-of-car')):</p>

 @({
  (equal (car x)
         (cond
          ((consp x)
           (car x))
          (t nil)))
 })

 <p>@(see Guard):</p>

 @({
  (or (consp x) (equal x nil))
 })

 <p>Notice that in the ACL2 logic, @('car') returns @('nil') for every @(see
 atom).</p>")

(defxdoc case
  :parents (basics acl2-built-ins)
  :short "Conditional based on if-then-else using @(tsee eql)"
  :long "@({
  Example Form:
  (case typ
    ((:character foo)
     (open file-name :direction :output))
    (bar (open-for-bar file-name))
    (otherwise
     (my-error "Illegal.")))
 })

 <p>is the same as</p>

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

 <p>which in turn is the same as</p>

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

 <p>Notice the quotations that appear in the example above: @(''(:character
 foo)') and @(''bar').  Indeed, a @('case') expression expands to a @(tsee
 cond) expression in which each tested form is quoted, and @(tsee eql) is used
 to test equality, as described below..</p>

 @({
  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))
 })

 <p>where each @('xi') is either @(tsee eqlablep) or a true list of @(tsee
 eqlablep) objects.  The final @('otherwise') or @('t') case is optional; if
 neither is present, then an equivalent expression results from adding the
 final case @('(t nil)').</p>

 <p>As suggested above, each case @('(xi val-i)') generates an if-then-else
 expression as follows.  If @('xi') is a non-nil atom (i.e., @('xi') is not
 @('nil') or a cons pair), then that case generates the expression @('(if (eql
 expr (quote xi)) vali ...)')  where `@('...')' denotes the expression
 generated by the rest of the cases.  If however @('xi') is a list, then
 instead the generated expression is @('(if (member expr (quote xi)) vali
 ...)').  The final case @('(t val-k+1)') or @('(otherwise val-k+1)') generates
 @('val-k+1').  Note that @('t') and @('otherwise') here must be in the
 @('"ACL2"') package.  Also note that to compare @('expr') with @('nil'), you
 should write the case as @('((nil) val-i)') rather than @('(nil val-i)')
 &mdash; and similarly for @('t') or @('otherwise') &mdash; that is, put the
 symbol in a list.</p>

 <p>@('Case') is defined in Common Lisp.  See any Common Lisp documentation for
 more information.</p>")

(defxdoc case-match
  :parents (basics acl2-built-ins)
  :short "Pattern matching or destructuring"
  :long "@({
  General Form:
  (case-match x
    (pat1 dcl1 ... body1)
    ...
    (patk dclk ... bodyk))
 })

 <p>where @('x') is a symbol, the @('pati') are structural patterns as
 described below, each &ldquo;@('dcli ...')&rdquo; indicates 0 or more @(tsee
 declare) forms, and the @('bodyi') are terms.  The legal @('declare') forms
 are the same as for @(tsee let): @('ignore'), @('ignorable'), and @('type').
 Return the value(s) of the @('bodyi') corresponding to the first @('pati')
 matching @('x'), or @('nil') if none matches.</p>

 <p>Pattern Language:<br></br>

 With the few special exceptions described below, matching requires that the
 @(tsee cons) structure of @('x') be isomorphic to that of the pattern, down to
 the @(see atom)s in the pattern.  Non-symbol @(see atom)s 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 (@(tsee
 EQUAL)) structure in every occurrence.</p>

 @({
  Exceptions:
  &               Matches anything and is not bound.  Repeated
                    occurrences of & in a pattern may match different
                    structures.
  nil, t, *sym*, :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.  This is the same as (QUOTE obj).
  (QUOTE~ sym)    where sym is a symbol, is like (QUOTE sym) except it
                    matches any symbol with the same symbol-name as sym.
                    Note that QUOTE~ is in the "ACL2" package.
 })

 <p>Some examples are shown below.</p>

 <p>Below we show some sample patterns and examples of things they match and do
 not match.</p>

 @({
  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)
 })

 <p>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:</p>

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

 <p>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.</p>

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

 <p>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.</p>

 <p>Technical point: The symbol @('sym') referenced by the symbol @('!sym') is
 in the same package as @('!sym') but with the leading exclamation point
 character, @('\#!'), removed from the @(tsee symbol-name) of @('!sym').</p>")

(defxdoc case-split
  :parents (rewrite linear
    type-prescription
    definition
    meta
    forward-chaining)
  :short "Like force but immediately splits the top-level goal on the hypothesis"
  :long "<p>@('Case-split') is a variant of @(tsee force), which has similar
 special treatment in hypotheses of rules for the same @(see rule-classes) as
 for @('force') (see @(see force)).  This treatment takes place for rule
 classes @(':')@(tsee rewrite), @(':')@(tsee linear), @(':')@(tsee
 type-prescription), @(':')@(tsee definition), @(':')@(tsee meta) (actually in
 that case, the result of evaluating the hypothesis metafunction call), and
 @(':')@(tsee forward-chaining).</p>

 <p>When a hypothesis of a conditional rule (of one of the classes listed
 above) has the form @('(case-split hyp)') it is logically equivalent to
 @('hyp').  However it affects the application of the rule generated as
 follows: if ACL2 attempts to apply the rule but cannot establish that the
 required instance of @('hyp') holds in the current context, it considers the
 hypothesis true anyhow, but (assuming all hypotheses are seen to be true and
 the rule is applied) creates a subgoal in which that instance of @('hyp') is
 assumed false.  (There are exceptions, noted below.)</p>

 <p>For example, given the rule</p>

 @({
  (defthm p1->p2
    (implies (case-split (p1 x))
             (p2 x)))
 })

 <p>then an attempt to prove</p>

 @({
  (implies (p3 x) (p2 (car x)))
 })

 <p>can give rise to a single subgoal:</p>

 @({
  (IMPLIES (AND (NOT (P1 (CAR X))) (P3 X))
           (P2 (CAR X))).
 })

 <p>Unlike @(tsee force), @('case-split') does not delay the ``false case'' to
 a forcing round but tackles it more or less immediately.</p>

 <p>The special ``split'' treatment of @('case-split') can be disabled by
 disabling forcing: see @(see force) for a discussion of disabling forcing, and
 also see @(see disable-forcing).  Finally, we should mention that the rewriter
 is never willing to split when there is an @(tsee if) term present in the goal
 being simplified.  Since @(tsee and) terms and @(tsee or) terms are merely
 abbreviations for @(tsee if) terms, they also prevent splitting.  Note that
 @(tsee if) terms are ultimately eliminated using the ordinary flow of the
 proof (but see @(see set-case-split-limitations)), so @('case-split') will
 ultimately function as intended.</p>

 <p>When in the interactive @(see proof-builder), @('case-split') behaves like
 @('force').</p>

 @(def case-split)")

(defxdoc case-split-limitations
  :parents (miscellaneous)
  :short "Limiting the number of immediate subgoals"
  :long "@({
  Examples:
  ACL2 !>(case-split-limitations (w state))
  (500 100)
 })

 <p>With the setting above, which is the default, @('clausify') will not try
 subsumption/replacement if more than 500 @(see clause)s are involved.
 Furthermore, the simplifier, as it sweeps over a clause, will inhibit further
 case splits when it has accumulated 100 subgoals.  To implement this
 inhibition, ACL2 refuses to rewrite subsequent literals, although it continues
 to split on any @('IF') calls in those literals.</p>

 <p>The following example illustrates how the latter restriction &mdash;
 specifically, not rewriting subsequent literals to avoid further case splits
 &mdash; can work.  We define a (rather nonsensical) function whose body
 introduces several cases.</p>

 @({
 (defun f1 (a b c)
   (if a
       (if b (equal c 0) (equal c 1))
     (if b (equal c 2) (equal c 3))))

 (set-case-split-limitations '(500 10))

 (set-gag-mode nil)

 (thm (or (equal (f1 a b c) xxx)
          (equal (f1 d e f) yyy)
          (equal (f1 g h i) zzz))
      :hints (("Goal" :in-theory (disable f1))
              ("Goal'" :in-theory (enable f1)))
      :otf-flg t)
 })

 <p>We show the output below.  The simplification of the original goal to Goal'
 replaces the original goal, which is the clause (i.e., disjunction) consisting
 of the single literal (i.e., term) shown above, to the clause consisting of
 three literals, namely, the list:</p>

 @({
 ; Goal', as a clause (disjunction of three literals)
 ((EQUAL (F1 A B C) XXX)
  (EQUAL (F1 D E F) YYY)
  (EQUAL (F1 G H I) ZZZ))
 })

 <p>That simplification is reflected in the value printed (as an implication)
 for Goal' in the output, below.  If we omit the call of @(tsee
 set-case-split-limitations) above, then we get 64 cases, from opening up the
 calls of @('f1') and splitting on the variables @('a'), @('b'), @('d'),
 @('e'), @('g'), and @('h').  But with the limit of 10 provided by
 set-case-split-limitations above, fewer cases are generated because rewriting
 of literals is inhibited, as explained below.  Here is the first part of the
 output for that limit of 10.</p>

 @({
 [Note:  A hint was supplied for the goal above.  Thanks!]

 This simplifies, using trivial observations, to

 [Note:  A hint was supplied for the goal below.  Thanks!]

 Goal'
 (IMPLIES (AND (NOT (EQUAL (F1 A B C) XXX))
               (NOT (EQUAL (F1 D E F) YYY)))
          (EQUAL (F1 G H I) ZZZ)).

 This simplifies, using the :definition F1 (if-intro), to the following
 thirteen conjectures.

 Subgoal 13
 (IMPLIES (AND A B (NOT (EQUAL (EQUAL C 0) XXX))
               (NOT (EQUAL (F1 D E F) YYY)))
          (EQUAL (F1 G H I) ZZZ)).
 })

 <p>Why, though, are there 13 cases, even though the limit was specified as 10?
 Initially, the first literal @('(EQUAL (F1 A B C) XXX)') was rewritten,
 splitting into four cases; and for each of those cases, the second literal was
 rewritten, splitting further; and so on.  However, the first time more than 10
 cases were generated was when there were 10 cases generated so far and a
 literal generated four cases &mdash; then since that one literal generated
 four cases, 4-1 = 3 cases were added to the 10 already generated.  From that
 point on, further rewriting of literals did not take place.</p>

 <p>In short: the first time a literal splits into enough cases so that the
 accumulated number of cases exceeds the limit, rewriting stops &mdash; but
 that last split can put us significantly past the limit specified.</p>

 <p>See @(see set-case-split-limitations) for a more general discussion.</p>")

(defxdoc cbd
  :parents (books-reference programming-with-state acl2-built-ins)
  :short "Connected book directory string"
  :long "@({
  Example:
  ACL2 !>:cbd
  "/usr/home/smith/"
 })

 <p>The connected book directory (``cbd'') is a string ending with the @('/')
 character that specifies a directory as an absolute pathname.  (See @(see
 pathname) for a discussion of file naming conventions.)  When utilities that
 take a filename argument, such as @(tsee include-book), are given a relative
 pathname, it is elaborated into an absolute pathname, essentially by
 appending the connected book directory string to the left and @('".lisp"')
 to the right.  (This absolute pathname is actually canonical when elaborating
 book names.  For more details on book names, see @(see book-name) and also see
 @(see full-book-name).)  Furthermore, @(tsee include-book) and @(tsee ld)
 temporarily set the connected book directory to the directory string of the
 resulting full pathname so that references to files in the same directory may
 omit the directory.  See @(see set-cbd) for how to set the connected book
 directory string.</p>

 <p>Note that the cbd is used for elaborating every @(see pathname) argument,
 not just a pathname that represents a book.  (Technical remark: Some
 utilities, such as @(tsee open-input-channel), use the cbd indirectly as
 follows.  That utility uses the Common Lisp utility, @('open'), which knows
 nothing about the cbd.  However, ACL2 arranges that the Lisp global
 @('*default-pathname-defaults*') always has the cbd as its value, and Lisp
 uses that global to elaborate relative pathnames much as ACL2 uses the
 cbd.)</p>

 @({
  General Form:
  (cbd)
 })

 <p>This is a macro that expands into a term involving the single free variable
 @(tsee state).  It returns the connected book directory string.</p>

 <p>For example, if the @('cbd') is @('"/usr/home/smith/"') then the @(see
 book-name) @('"project/task-1/arith"') is elaborated using the @('cbd') to
 the @(see full-book-name) @('"/usr/home/smith/project/task-1/arith.lisp"'),
 which is what @(see include-book) opens to read the source text for the
 book.</p>

 <p>The @('cbd') may be changed using @(tsee set-cbd).</p>

 <p>As noted above, during the processing of the @(see events) in a book,
 @(tsee include-book) sets the @('cbd') to be the directory string of the @(see
 full-book-name) of the book; similarly for @(tsee ld).  Thus, if the @('cbd')
 is @('"/usr/home/smith/"') then during the processing of @(see events)
 by</p>

 @({
  (include-book "project/task-1/arith")
 })

 <p>the @('cbd') will be set to @('"/usr/home/smith/project/task-1/"').  Note
 that if @('"arith"') recursively includes a sub-book, say @('"naturals"'),
 that resides on the same directory, the @(tsee include-book) event for it may
 omit the specification of that directory.  For example, @('"arith"') might
 contain the event</p>

 @({
    (include-book "naturals").
 })

 <p>In general, suppose we have a superior book and several inferior @(see
 books) which are included by @(see events) in the superior book.  Any inferior
 book residing on the same directory as the superior book may be referenced in
 the superior without specification of the directory.</p>

 <p>We call this a ``relative'' as opposed to ``absolute'' naming.  The use of
 relative naming is preferred because it permits @(see books) (and their
 accompanying inferiors) to be moved between directories while maintaining
 their @(see certificate)s and utility.  Certified @(see books) that reference
 inferiors by absolute file names are unusable (and rendered uncertified) if
 the inferiors are moved to new directories.</p>")

(defxdoc ccl-installation
  :parents (obtaining-common-lisp)
  :short "Installing Clozure Common Lisp (CCL)"
  :long "<p>For those who use ACL2 built on CCL as the host Common Lisp
 implementation, it has been common practice to use the latest GitHub version
 of CCL.  We provide the following instructions for you to choose from.  The
 ``brief'' instructions for Linux or Mac (according to your operating system)
 might well suffice; the ``elaborate'' instructions have helped with version
 control.</p>

 <ul>

 <li>@(see ccl-installation-linux-brief)</li>

 <li>@(see ccl-installation-mac-brief)</li>

 <li>@(see ccl-installation-linux-elaborate)</li>

 <li>@(see ccl-installation-mac-elaborate)</li>

 </ul>

 <p>You may prefer instead to look at the <a
 href='https://github.com/Clozure/ccl/releases'>CCL Releases</a> page, which
 has potentially more up-to-date information; then you can use the links above
 only as needed (e.g., for Linux-specific information or for discussion of
 @('CCL_DEFAULT_DIRECTORY')).</p>

 <p>One of the links listed above should generally suffice.  But if you
 would like additional information on CCL installation and implementation, see
 @(see ccl-installation-extra).</p>")

(defxdoc ccl-installation-extra
  :parents (ccl-installation)
  :short "Clozure Common Lisp (CCL) installation and implementation details"
  :long "<p><b>NOTE</b>: See <a
 href='https://github.com/Clozure/ccl/releases/'>the Clozure CL releases
 page</a> for the latest information, which may supersede some of what is
 included below.</p>

 <p>This topic, contributed by Warren A. Hunt, Jr., extends the basic
 information given in @(see ccl-installation).  It may be useful to some,
 especially those who use ACL2 in ways that particularly stress memory.
 Another resource may be found on <a
 href='https://github.com/Clozure/ccl/releases/'>this page</a>.</p>

 <p>Below we provide instructions to build CCL on FreeBSD and MacOS; building
 on Linux will be similar.  Before providing the build instructions, we mention
 a few facts about CCL's implementation.</p>

 <p>CCL's implementation can't expand stack space automatically.  The sizes of
 various stacks are set at thread creation time.  Most programs don't need very
 big stacks.  The CCL default value and temp stack sizes may be too small for
 compute-intensive applications.</p>

 <p>The various stack sizes are set when creating a thread with code in
 @('CCL::MAKE-PROCESS') and @('CCL::PROCESS-RUN-FUNCTION'), and they set the
 three stack sizes of the initial listener thread that is created when CCL
 starts.</p>

 <p>The value stack is used for data in deeply-nested lisp recursion.  ACL2 can
 benefit from an increase in the size of the value stack.</p>

 <p>The temp stack is used for dynamic-extent objects.  This might need need to
 be larger than the default.</p>

 <p>The control stack is used to run C and binary code; it would be surprising
 to need to increase its size.</p>

 <p>If only one or two threads are needed, giant (e.g., 4 GB) stacks can
 be OK, but with many threads large stacks use lots of memory.  Below
 are the stacks along with their current (April, 2020) default sizes.</p>

  @({
  ccl::*default-control-stack-size*                    ;; default 2^21
  ccl::*initial-listener-default-control-stack-size*   ;; default 2^21

  ccl::*default-value-stack-size*                      ;; default 2^21
  ccl::*initial-listener-default-value-stack-size*     ;; default 2^21

  ccl::*initial-listener-default-temp-stack-size*      ;; default 2^20
  ccl::*default-temp-stack-size*                       ;; default 2^20
  })

 <p>If we are running on a 32-bit platform, we set the stack sizes modestly.
 If we are on a 64-bit platform, we set the stack sizes to much larger
 values.  See the later discussion about ``configure-ccl.lisp'' below to
 see how to alter (increase) stack sizes.</p>

 <h3>MacOS Build Instructions:</h3>

 @({
 git clone https://github.com/Clozure/ccl.git ccl-dev
 curl -L -O https://github.com/Clozure/ccl/releases/download/v1.12-dev.5/darwinx86.tar.gz
 cd ccl-dev ; tar xf ../darwinx86.tar.gz
 })

 <p>Rebuild C-based, Lisp kernel</p>

 <p>To rebuild the Lisp-code part of the kernel, do...</p>

 @({
 cd lisp-kernel/darwinx8664 ; make ; cd ../..
 })

 <p>Unlike for FreeBSD and Linux, we exclude ``:full t'' from the
 ``rebuild-ccl'' command just below Matt Emerson (a CCL expert) writes:</p>

 <blockquote>

 <p>After looking at your log, I was able to duplicate the problem myself.
 For some reason I do not understand, it appears that on Catalina,
 removing the running lisp kernel binary causes run-program to break
 (trying to run external programs gets signal 9).  This surprises me
 very much.</p>

 <p>One of the effects of running (rebuild-ccl :full t), is that it first does
 a "make clean" in the lisp kernel directory, and then does a regular make.
 This has worked for years, and I do not know why it has stopped working.</p>

 </blockquote>

 <p>To avoid this, rebuild the lisp with (rebuild-ccl :clean t) instead.  Do
 not specify ``@(':full t')''.  Since you have already built the lisp kernel,
 you gain nothing from ``@(':full t')'' doing it again.  So, once the C-based,
 Lisp kernel is built, then do:</p>

 @({
 echo "(in-package :ccl) (rebuild-ccl :verbose t :clean t)" | \
       ./dx86cl64 -n |& tee ./ccl-build-compile.log
 })

 <p>Matt Emerson suggests that one re-build again.  We asked Matt a
 long-simmering question: we have been told that it is a good idea to compile
 CCL twice.  Is that so that the CCL compiler produced by pass one on the
 target system is used to compile the CCL system that will be used (on the
 target system)?  Or, is compiling twice some silly myth?  Matt Emerson
 responded:</p>

 <blockquote>

 <p>It's not entirely mythic.  Some rare changes do need the lisp to be rebuilt
 twice for bootstrapping purposes, but usually it isn't required.</p>

 </blockquote>

 <p>Thus, we recommend you re-build (compile) the Lisp code again.</p>

 @({
 echo "(in-package :ccl) (rebuild-ccl :verbose t :clean t)" | \
       ./dx86cl64 -n |& tee ./ccl-build-compile-2.log
 })

 <p>Finally, one may specialize the final image by:</p>

 @({
 cat configure-ccl.lisp | ./dx86cl64 -n |& tee ~/ccl-build-specialize.log
 })

 <p>where ``configure-ccl.lisp'' (not supplied) contains whatever CCL
 specialization commands you wish to have in the version of CCL you use for
 ACL2 or other work.  See the end of this note for an example of
 ``configure-ccl.lisp''.</p>

 <h3>FreeBSD Build Instructions:</h3>

 <p>The FreeBSD build instructions are similar to the MacOS build instruction,
 but the names are changed appropriately.</p>

 @({
 git clone https://github.com/Clozure/ccl.git ccl-dev
 curl -L -O https://github.com/Clozure/ccl/releases/download/v1.12-dev.5/freebsd12-x8664.tar.gz
 cd ccl-dev
 tar xf ../freebsd12-x8664.tar.gz
 })

 <p>Rebuild C-based Lisp kernel</p>

 @({
 cd lisp-kernel/freebsdx8664 ; make ; cd ../..
 })

 <p>To rebuild the Lisp-code part of the kernel, do...</p>

 @({
 echo "(in-package :ccl) (rebuild-ccl :full t :verbose t :clean t)" | \
       ./fx86cl64 -n |& tee ./ccl-build-compile.log
 })

 <p>FreeBSD is OK with the ``:full t'' flag, which as of MacOS 10.15
 breaks (but used to work on earlier versions of MacOS).  So, this
 option persists on the FreeBSD build.</p>

 <p>Matt Emerson recommends building the Lisp code a second time; see
 the ``MacOS Build Instructions'' above for his rationale.</p>

 @({
 echo "(in-package :ccl) (rebuild-ccl :full t :verbose t :clean t)" | \
       ./fx86cl64 -n |& tee ./ccl-build-compile-2.log
 })

 <p>Finally, one may specialize the final image by:</p>

 @({
 cat ~/a/scripts/configure-ccl.lisp | ./fx86cl64 -n |& tee ~/ccl-build-specialize.log
 })

 <p>where ``configure-ccl.lisp'' (not supplied) contains whatever CCL
 specialization commands you wish to have in the version of CCL you use for
 ACL2 or other work.</p>

 <code><h3>configure-ccl.lisp</h3></code>

 <p>Sample ``configure-ccl.lisp'' file for 64-bit implementation:</p>

 @({
 (progn
   ;; Parameters to configure CCL for use on FreeBSD and MacOS

   (in-package :ccl)

   ;; Enlarge stack sizes
   (setq *default-value-stack-size*                    (expt 2 28))
   (setq *initial-listener-value-stack-size*           (expt 2 28))

   (setq *default-temp-stack-size*                     (expt 2 24))
   (setq *initial-listener-temp-stack-size*            (expt 2 24))

   (setq *default-control-stack-size*                  (expt 2 24))
   (setq *initial-listener-default-control-stack-size* (expt 2 24))

   ;; For CCL double precision
   (setf *read-default-float-format* 'double-float)

   ;; Make DEFUN save the source code for later recovery via
   ;; FUNCTION-LAMBDA-EXPRESSION.
   (setq *save-definitions* t)
   (setq *fasl-save-definitions* t)

   ;; Make GC verbose; see ACL2 documentation topic GC-VERBOSE.
   (gc-verbose t t)

   ;; Dump executable heap image; see ACL2 documentation topic SAVE-EXEC.
   (save-exec *heap-image-name* "Modification string to print at startup")
   )
 })")

(defxdoc ccl-installation-linux-brief
  :parents (ccl-installation)
  :short "Installing Clozure Common Lisp (CCL) on Linux (brief version)"
  :long "<p><b>NOTE:</b> See <a
 href='https://github.com/Clozure/ccl/releases/'>the Clozure CL releases
 page</a> for the latest information, which probably supersedes what is
 included below.</p>

 <p>See @(see ccl-installation) for introductory remarks.  The instructions
 below describe how to install CCL on Linux.  For more elaborate ``cookbook''
 instructions see @(see ccl-installation-linux-elaborate).</p>

 <p><b>Note</b>: Linux users may need to install m4.</p>

 <p>Fetch CCL from GitHub into a fresh subdirectory, @('ccl/').</p>

 @({
 git clone https://github.com/Clozure/ccl
 })

 <p>Next fetch and extract a development snapshot in the new @('ccl')
 directory.  <b>WARNING.</b>  The version below is current as of this
 writing (November, 2023), but see <a
 href='https://github.com/Clozure/ccl/releases/'>https://github.com/Clozure/ccl/releases/</a>
 for the latest snapshots; in particular, @('"v1.12.2"') below could change,
 e.g., to @('"v1.12.3"') or @('"v1.13"').</p>

 @({
 cd ccl
 wget https://github.com/Clozure/ccl/releases/download/v1.12.2/linuxx86.tar.gz
 tar xfz linuxx86.tar.gz
 })

 <p>Rebuild and quit, twice.</p>

 @({
 echo '(rebuild-ccl :full t)' | ./lx86cl64
 echo '(rebuild-ccl :full t)' | ./lx86cl64
 })

 <p>Create the following executable script, which you will probably want to
 name @('"ccl"'), where @('<DIR>') is the absolute pathname (without using
 ``@('~')'') of the directory in which you issued the ``@('git clone')''
 command.  Place this script wherever you wish, though putting it in a
 directory on your Unix @('PATH') might be helpful (since then you can invoke
 it as, say @('"ccl"')).</p>

 @({
 #!/bin/sh

 export CCL_DEFAULT_DIRECTORY=<DIR>/ccl
 ${CCL_DEFAULT_DIRECTORY}/scripts/ccl64 "$@"
 })

 <p>You're done!  (Note however that certification of @(see books) that use
 @(see Quicklisp) may require @('openssl') to be installed if it is not already
 on your system.)</p>")

(defxdoc ccl-installation-linux-elaborate
  :parents (ccl-installation)
  :short "Installing Clozure Common Lisp (CCL) on Linux (elaborate version)"
  :long "<p><b>NOTE:</b> See <a
 href='https://github.com/Clozure/ccl/releases/'>the Clozure CL releases
 page</a> for the latest information, which may well supersede what is included
 below.</p>

 <p>See @(see ccl-installation) for introductory remarks.  The ``cookbook''
 instructions below give you one way to install CCL on Linux without any
 knowledge of git or CCL.  For more streamlined instructions see @(see
 ccl-installation-linux-brief).</p>

 <p><b>Note</b>: Linux users may need to install m4.</p>

 <p>First fetch CCL from GitHub as follows.  (You may prefer to use ``@('git
 pull')'' if you previously did this step.  In that case you probably won't
 want to do the optional renaming of the directory, mentioned below.)</p>

 @({
 # Obtain a ccl distribution in a fresh directory:
 mkdir temp
 cd temp
 git clone https://github.com/Clozure/ccl
 # Optionally rename that directory as suggested below, after
 # executing the following three commands.
 cd ccl
 git rev-parse HEAD
 cd ../../
 # Optionally change directory name, and then go back to ccl directory:
 # You'll want the last 10 hex digits to match those of the
 # output from the ``git rev-parse HEAD'' command above: do
 # that twice here and once further below.
 mv temp 2017-12-07-6be8298fe5
 cd 2017-12-07-6be8298fe5/ccl
 })

 <p>Next fetch and extract a development snapshot in the new @('ccl')
 directory.  <b>WARNING.</b>  The version below is current as of this
 writing (November, 2023), but see <a
 href='https://github.com/Clozure/ccl/releases/'>https://github.com/Clozure/ccl/releases/</a>
 for the latest snapshots; in particular, @('"v1.12.2"') below could change,
 e.g., to @('"v1.12.3"') or @('"v1.13"').</p>

 @({
 wget https://github.com/Clozure/ccl/releases/download/v1.12.2/linuxx86.tar.gz
 tar xfz linuxx86.tar.gz
 })

 <p>Rebuild and quit, twice.</p>

 @({
 echo '(rebuild-ccl :full t)' | ./lx86cl64
 echo '(rebuild-ccl :full t)' | ./lx86cl64
 })

 <p>Create an executable script like the following.  You might want to call it
 ``@('ccl')'' and put it into a directory on your path.  Be sure to change the
 name (shown as ``2017-12-07-6be8298fe5'' above) to match the name change
 already made above.</p>

 @({
 #!/bin/sh

 export CCL_DEFAULT_DIRECTORY=/projects/acl2/lisps/ccl/2017-12-07-6be8298fe5/ccl
 ${CCL_DEFAULT_DIRECTORY}/scripts/ccl64 "$@"
 })

 <p>Now ensure that your script is executable, e.g.:</p>

 @({
 chmod +x my-script
 })

 <p>You're done!  (Note however that certification of @(see books) that use
 @(see Quicklisp) may require @('openssl') to be installed if it is not already
 on your system.)</p>")

(defxdoc ccl-installation-mac-brief
  :parents (ccl-installation)
  :short "Installing Clozure Common Lisp (CCL) on Mac (brief version)"
  :long "<p><b>NOTE:</b> See <a
 href='https://github.com/Clozure/ccl/releases/'>the Clozure CL releases
 page</a> for the latest information, which probably supersedes what is
 included below.</p>

 <p>See @(see ccl-installation) for introductory remarks.  The instructions
 below describe how to install CCL on a Mac (Darwin).  For more elaborate
 ``cookbook'' instructions see @(see ccl-installation-mac-elaborate).</p>

 <p>Fetch CCL from GitHub into a fresh subdirectory, @('ccl/').</p>

 @({
 git clone https://github.com/Clozure/ccl
 })

 <p>Next fetch and extract a development snapshot in the new @('ccl')
 directory.  <b>WARNING.</b>  The version below is current as of this
 writing (November, 2023), but see <a
 href='https://github.com/Clozure/ccl/releases/'>https://github.com/Clozure/ccl/releases/</a>
 for the latest snapshots; in particular, @('"v1.12.2"') below could change,
 e.g., to @('"v1.12.3"') or @('"v1.13"').</p>

 @({
 cd ccl
 curl -O -L https://github.com/Clozure/ccl/releases/download/v1.12.2/darwinx86.tar.gz
 tar xfz darwinx86.tar.gz
 })

 <p>Rebuild the lisp kernel by hand before trying to rebuild the lisp.</p>

 @({
 cd lisp-kernel/darwinx8664; make clean; make
 cd -
 })

 <p>Rebuild and quit, twice.</p>

 @({
 echo '(rebuild-ccl :clean t)' | ./dx86cl64
 echo '(rebuild-ccl :clean t)' | ./dx86cl64
 })

 <p>Create the following executable script, which you will probably want to
 name @('"ccl"'), where @('<DIR>') is the absolute pathname (without using
 ``@('~')'') of the directory in which you issued the ``@('git clone')''
 command.  Place this script wherever you wish, though putting it in a
 directory on your Unix @('PATH') might be helpful (since then you can invoke
 it as, say @('"ccl"')).</p>

 @({
 #!/bin/sh

 export CCL_DEFAULT_DIRECTORY=<DIR>/ccl
 ${CCL_DEFAULT_DIRECTORY}/scripts/ccl64 "$@"
 })

 <p>You're done!  (Note however that certification of @(see books) that use
 @(see Quicklisp) may require @('openssl') to be installed if it is not already
 on your system.)</p>")

(defxdoc ccl-installation-mac-elaborate
  :parents (ccl-installation)
  :short "Installing Clozure Common Lisp (CCL) on Mac (elaborate version)"
  :long "<p><b>NOTE:</b> See <a
 href='https://github.com/Clozure/ccl/releases/'>the Clozure CL releases
 page</a> for the latest information, which may well supersede what is included
 below.</p>

 <p>See @(see ccl-installation) for introductory remarks.  The ``cookbook''
 instructions below give you one way to install CCL on a Mac
 (Darwin) without any knowledge of git or CCL.  For more streamlined
 instructions see @(see ccl-installation-mac-brief).</p>

 <p>First fetch CCL from GitHub as follows.  (You may prefer to use ``@('git
 pull')'' if you previously did this step.  In that case you probably won't
 want to do the optional renaming of the directory, mentioned below.)</p>

 @({
 # Obtain a ccl distribution in a fresh directory:
 mkdir temp
 cd temp
 git clone https://github.com/Clozure/ccl
 # Optionally rename that directory as suggested below, after
 # executing the following three commands.
 cd ccl
 git rev-parse HEAD
 cd ../../
 # Optionally change directory name, and then go back to ccl directory:
 # You'll want the last 10 hex digits to match those of the
 # output from the ``git rev-parse HEAD'' command above: do
 # that twice here and once further below.
 mv temp 2017-12-07-6be8298fe5
 cd 2017-12-07-6be8298fe5/ccl
 })

 <p>Next fetch and extract a development snapshot in the new @('ccl')
 directory.  <b>WARNING.</b>  The version below is current as of this
 writing (November, 2023), but see <a
 href='https://github.com/Clozure/ccl/releases/'>https://github.com/Clozure/ccl/releases/</a>
 for the latest snapshots; in particular, @('"v1.12.2"') below could change,
 e.g., to @('"v1.12.3"') or @('"v1.13"').</p>

 @({
 curl -L -O https://github.com/Clozure/ccl/releases/download/v1.12.2/darwinx86.tar.gz
 tar xfz darwinx86.tar.gz
 })

 <p>Rebuild the lisp kernel by hand before trying to rebuild the lisp.
 (Note: This step was formerly unnecessary and might become unnecessary again,
 but it seems to have been necessary on MacOS Catalina (10.15).</p>

 @({
 cd lisp-kernel/darwinx8664; make clean; make
 cd -
 })

 <p>Rebuild and quit, twice.</p>

 @({
 echo '(rebuild-ccl :clean t)' | ./dx86cl64
 echo '(rebuild-ccl :clean t)' | ./dx86cl64
 })

 <p>Create an executable script like the following.  You might want to call it
 ``@('ccl')'' and put it into a directory on your path.  Be sure to change the
 name (shown as ``2017-12-07-6be8298fe5'' above) to match the name change
 already made above.</p>

 @({
 #!/bin/sh

 export CCL_DEFAULT_DIRECTORY=/projects/acl2/lisps/ccl/2017-12-07-6be8298fe5/ccl
 ${CCL_DEFAULT_DIRECTORY}/scripts/ccl64 "$@"
 })

 <p>Now ensure that your script is executable, e.g.:</p>

 @({
 chmod +x my-script
 })

 <p>You're done!  (Note however that certification of @(see books) that use
 @(see Quicklisp) may require @('openssl') to be installed if it is not already
 on your system.)</p>")

(defxdoc cdaaar
  :parents (conses acl2-built-ins)
  :short "@(tsee cdr) of the @(tsee caaar)"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc cdaadr
  :parents (conses acl2-built-ins)
  :short "@(tsee cdr) of the @(tsee caadr)"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc cdaar
  :parents (conses acl2-built-ins)
  :short "@(tsee cdr) of the @(tsee caar)"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc cdadar
  :parents (conses acl2-built-ins)
  :short "@(tsee cdr) of the @(tsee cadar)"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc cdaddr
  :parents (conses acl2-built-ins)
  :short "@(tsee cdr) of the @(tsee caddr)"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc cdadr
  :parents (conses acl2-built-ins)
  :short "@(tsee cdr) of the @(tsee cadr)"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc cdar
  :parents (conses acl2-built-ins)
  :short "@(tsee cdr) of the @(tsee car)"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc cddaar
  :parents (conses acl2-built-ins)
  :short "@(tsee cdr) of the @(tsee cdaar)"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc cddadr
  :parents (conses acl2-built-ins)
  :short "@(tsee cdr) of the @(tsee cdadr)"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc cddar
  :parents (conses acl2-built-ins)
  :short "@(tsee cdr) of the @(tsee cdar)"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc cdddar
  :parents (conses acl2-built-ins)
  :short "@(tsee cdr) of the @(tsee cddar)"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc cddddr
  :parents (conses acl2-built-ins)
  :short "@(tsee cdr) of the @(tsee cdddr)"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc cdddr
  :parents (conses acl2-built-ins)
  :short "@(tsee cdr) of the @(tsee cddr)"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc cddr
  :parents (conses acl2-built-ins)
  :short "@(tsee cdr) of the @(tsee cdr)"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc cdr
  :parents (conses acl2-built-ins)
  :short "Returns the second element of a @(tsee cons) pair, else @('nil')"
  :long "<p>Completion Axiom (@('completion-of-cdr')):</p>

 @({
  (equal (cdr x)
         (cond
          ((consp x)
           (cdr x))
          (t nil)))
 })

 <p>@(see Guard):</p>

 @({
  (or (consp x) (equal x nil))
 })

 <p>Notice that in the ACL2 logic, @('cdr') returns @('nil') for every @(see
 atom).</p>")

(defxdoc ceiling
  :parents (numbers acl2-built-ins)
  :short "Division returning an integer by truncating toward positive infinity"
  :long "@({
  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
 })

 <p>@('(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').</p>

 <p>The @(see guard) for @('(ceiling i j)') requires that @('i') and @('j') are
 rational (@(see real), in ACL2(r)) numbers and @('j') is non-zero.</p>

 <p>@('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,</p>

 @(def ceiling)")

(defxdoc certificate
  :parents (books-tour)
  :short "A file specifying validity of a given book"
  :long "<p>A book, say @('"arith"'), is said to have a ``certificate'' if
 there is a file named @('"arith.cert"').  Certificates are created by the
 function @(tsee certify-book) and inspected by @(tsee include-book).  @(Csee
 book-hash) values are used to help ensure that certificates are legitimate and
 that the corresponding book has not been modified since certification.  But
 because the file system is insecure and book-hash values are not perfect, it
 is possible for the inclusion of a book to cause inconsistency even though the
 book carries an impeccable certificate.</p>

 <p>The certificate includes the version number of the certifying ACL2.  A book
 is considered uncertified if it is included in an ACL2 with a different @(see
 version) number.</p>

 <p>The presence of a ``valid'' certificate file for a book attests to two
 things: all of the @(see events) of the book are admissible in a certain
 extension of the initial ACL2 logic, and the non-@(tsee local) @(see events)
 of the book are independent of the @(tsee local) ones (see @(see
 local-incompatibility)).  In addition, the certificate contains the @(see
 command)s used to construct the @(see world) in which certification occurred.
 Among those @(see command)s, of course, are the @(tsee defpkg)s defining the
 packages used in the book.  When a book is included into a host @(see world),
 that @(see world) is first extended by the @(see command)s listed in the
 certificate for the book.  Unless that causes an error due to name conflicts,
 the extension ensures that all the packages used by the book are identically
 defined in the host @(see world).</p>

 <p><i>Security:</i></p>

 <p>Because the host file system is insecure, there is no way ACL2 can
 guarantee that the contents of a book remain the same as when its certificate
 was written.  That is, between the time a book is certified and the time it is
 used, it may be modified.  Furthermore, certificates can be counterfeited.
 @(csee Book-hash) values are used to help detect such problems, but provide
 imperfect security: two different files can have the same book-hash.</p>

 <p>Therefore, from the strictly logical point of view, one must consider even
 the inclusion of certified @(see books) as placing a burden on the user:</p>

 <blockquote>

 <p>The non-erroneous inclusion of a certified book is consistency preserving
 provided (a) the objects read by @(tsee include-book) from the certificate
 were the objects written there by a @(tsee certify-book) and (b) the forms
 read by @(tsee include-book) from the book itself are the forms read by the
 corresponding @(tsee certify-book).</p>

 </blockquote>

 <p>We say that a given execution of @(tsee include-book) is ``certified'' if a
 certificate file for the book is present and well-formed and the @(see
 book-hash) information contained within it supports the conclusion that the
 @(see events) read by the @(tsee include-book) are the ones checked by @(tsee
 certify-book).  When an uncertified @(tsee include-book) occurs, warnings are
 printed or errors are caused.  But even if no warning is printed, you must
 accept burdens (a) and (b) if you use @(see books).  These burdens are easier
 to live with if you protect your @(see books) so that other users cannot write
 to them, you abstain from running concurrent ACL2 jobs, and you abstain from
 counterfeiting certificates.  But even on a single user uniprocessor, you can
 shoot yourself in the foot by using the ACL2 @(see io) primitives to fabricate
 an inconsistent book and the corresponding certificate.</p>

 <p>Note that part (a) of the burden described above implies, in particular,
 that there are no guarantees when a certificate is copied.  When @(see books)
 are renamed (as by copying them), it is recommended that their certificates be
 removed and the @(see books) be recertified.  The expectation is that
 recertification will go through without a hitch if relative @(see pathname)s
 are used.  See @(see pathname), which is not on the guided tour.</p>

 <p>Certificates contain a @(see portcullis) and a @(see keep), each documented
 later in this guided tour through @(see books).  We mention here two other
 parts, which we do not document elsewhere because we view them as
 implementation details: an @('expansion-alist'), which records @(tsee
 make-event) expansions; and @('cert-data'), which contains logical information
 associated with the book.  (Those curious about @('cert-data') are invited to
 look at the ``Essay on Cert-data'' in the source code.)</p>

 <p>See @(see portcullis) to continue the guided tour through @(see
 books).</p>")

(defxdoc certify-book
  :parents (books-reference books-tour)
  :short "How to produce a @(see certificate) for a book"
  :long "<p>Also see @(see certificate) for information about the
 @('".cert"') file produced by @('certify-book'), in particular for
 information about the use of @(see book-hash) values to help ensure that the
 corresponding book has not been modified since certification.  See @(see
 certify-book-debug) for some potential remedies for failures of
 @('certify-book').</p>

 @({
  Examples:
  (certify-book "my-arith")          ; certify in a world with 0 commands
  (certify-book "my-arith" 3)        ; ... in a world with 3 commands
  (certify-book "my-arith" ?)        ; ... in a world without checking the
                                     ;     number of commands
  (certify-book "my-arith" 0 nil)    ; ... without compilation
  (certify-book "my-arith" 0 t)      ; ... with compilation (default)
  (certify-book "my-arith" 0 t :ttags (foo))
                                     ; ... allowing trust tag (ttag) foo
  (certify-book "my-arith" 0 t :ttags :all)
                                     ; ... allowing all trust tags (ttags)
  (certify-book "my-arith" 0 nil :acl2x t)
                                     ; ... writing or reading a .acl2x file
  (certify-book "my-arith" 0 t :useless-runes :write)
                                     ; ... write file to speed up future proofs
  (certify-book "my-arith" 0 t :useless-runes :read)
                                     ; ... read file to speed up future proofs

  General Form:
  (certify-book book-name
                k                       ; [default 0]
                compile-flg             ; [default t]
                :defaxioms-okp t/nil    ; [default nil]
                :skip-proofs-okp t/nil  ; [default nil]
                :ttags ttags            ; [default nil]
                :acl2x t/nil            ; [default nil]
                :ttagsx ttags           ; [default nil]
                :pcert pcert            ; [default nil]
                :write-port t/nil       ; [default t unless pcert is non-nil]
                :useless-runes          ; :write/:read/:read?/n/-n/nil
                                        ;   (-100 < n < 0 or 0 < n <= 100)
                                        ;   [default nil or from environment]
                :write-event-data       ; [default nil or from environment]
                )
 })

 <p>where @('book-name') is a book filename, @('k') is used to indicate your
 approval of the ``certification @(see world),'' and @('compile-flg') can
 control whether the book is to be compiled.  The defaults for
 @('compile-flg'), @('skip-proofs-okp'), @('acl2x'), @('write-port'),
 @('pcert'), @(':useless-runes'), and @(':write-event-data') can be affected by
 environment variables.  All of these arguments are described in detail below,
 except for @(':pcert'), @(':useless-runes'), and @(':write-event-data'): see
 @(see provisional-certification), @(see useless-runes), and @(see
 saving-event-data), respectively, for the effects of these three arguments and
 related environment variables, as we ignore those effects in the present
 topic.</p>

 <p>NOTE: If a given book includes some books (see @(see include-book)), then
 those included books need to be certified before the given book is certified.
 See @(see build::cert.pl) for a tool that certifies not only a given book but
 also all of the books that it includes, as well as all the books that those
 books include, and so on &mdash; all in the proper order, and with parallelism
 by using the @('-j') option.</p>

 <p>Certification occurs in some logical @(see world), called the
 ``certification @(see world).''  That @(see world) must contain the @(tsee
 defpkg)s needed to read and execute the forms in the book.  The @(see
 command)s necessary to recreate that @(see world) from the ACL2 initial @(see
 world) are called the ``@(see portcullis) commands,'' and will be copied into
 the @(see certificate) created for the book.  Those @(see command)s will be
 re-executed whenever the book is included, to ensure that the appropriate
 packages (and all other names used in the certification @(see world)) are
 correctly defined.  Note that Step 1 of @('certify-book') will fail if a
 package mentioned in the book is not defined before attempting the
 certification, i.e., defined by a portcullis command in the certification
 world.  For example, suppose that your book contains the symbol @('FOO::X'),
 but the package "FOO" is not currently defined.  Then an error message will
 likely complain either about a missing package @('"FOO"'), or about a symbol
 @('FOO::X') that is ``not in any of the packages known to ACL2.''  A solution
 is to define the package "FOO", perhaps directly using @(tsee defpkg) or by
 including a book that defines this package, before attempting the
 certification.</p>

 <p>The certified book will be more often usable if the certification @(see
 world) is kept to a minimal extension of the ACL2 initial @(see world) (for
 example, to prevent name clashes with functions defined in other books, or to
 avoid including undesired rules).  Alternatively, use @(tsee local) @(see
 events) to build your certification world, as these will be skipped when
 including the certified book.  But perhaps it's simplest just to get into the
 initial ACL2 @(see world) (e.g., with @(':ubt 1') or by just starting a new
 ACL2 run), then define the desired packages (directly with @(tsee defpkg) or
 by including books that define the packages), and finally invoke
 @('certify-book').</p>

 <p>The @('k') argument to @('certify-book') has default value @('0'), and it
 must be either a nonnegative integer or else the symbol @('?') in any package.
 If @('k') is an integer, then it must be the number of @(see command)s that
 have been executed after the initial ACL2 @(see world) to create the @(see
 world) in which @('certify-book') was called.  One way to obtain this number
 is by doing @(':pbt :start') to see all the @(see command)s back to the first
 one.</p>

 <p>Otherwise, @('k') is @('?') (or any symbol whose @(tsee symbol-name) is
 @('"?"')).  In that case there is no check made on the certification world.
 This can be a nice convenience but at the cost of eliminating a potentially
 valuable check that the certification @(see world) may be as expected.</p>

 <p>We next describe the meaning of @('compile-flg') and how it defaults.  If
 explicit compilation has been suppressed by @('(set-compiler-enabled nil
 state)'), then @('compile-flg') is coerced to @('nil'); see @(see
 compilation).  Otherwise @('compile-flg') may be given the value of @('t') (or
 @(':all'), which is equivalent to @('t') except during provisional
 certification; see @(see provisional-certification)), indicating that the book
 is to be compiled, or else @('nil').  (Note that compilation initially creates
 a compiled file with a temporary file name, and then moves that temporary file
 to the final compiled file name obtained by adding a suitable extension to the
 book's filename.  Thus, a compiled file will appear atomically in its intended
 location.)  Finally, if @('compile-flg') is not supplied (or is @(':default'))
 then it is treated as @('t').  Note that the value @(':all') is equivalent to
 @('t') except for during the Convert procedure of provisional certification;
 see @(see provisional-certification).</p>

 <p>Two keyword arguments, @(':defaxioms-okp') and @(':skip-proofs-okp'),
 determine how the system handles the inclusion of @(tsee defaxiom) events and
 @(tsee skip-proofs) events, respectively, in the book.  The value @('t')
 allows such events, but prints a warning message.  The value @('nil') causes
 an error if such an event is found.  @('Nil') is the default unless keyword
 argument @(':acl2x t') is provided and state global @(''write-acl2x') is a
 cons (see @(see set-write-acl2x)), in which case the default is @('t').</p>

 <p>The keyword argument @(':ttags') may normally be omitted.  A few
 constructs, used for example if you are building your own system based on
 ACL2, may require it.  See @(see defttag) for an explanation of this
 argument.</p>

 <p>When book @('B') is certified with value @('t') (the default, unless the
 value used for @('pcert') is non-@('nil')) for keyword argument
 @(':write-port'), a file @('B.port') is written by certification process.
 This file contains all of the @(see portcullis) @(see command)s for @('B'),
 i.e., all user commands present in the ACL2 logical @(see world) at the time
 @('certify-book') is called.  If @('B.lisp') later becomes uncertified, say
 because @(see events) from that file or an included book have been edited,
 then @('(include-book "B")') will consult @('B.port') to evaluate forms in
 that file before evaluating the events in @('B.lisp').  On the other hand,
 @('B.port') is ignored when including @('B') if @('B') is certified.</p>

 <p>If you use @(see guard)s, please note @('certify-book') is executed as
 though @('(set-guard-checking t)') has been evaluated; see @(see
 set-guard-checking).  If you want to run with different guard-checking,
 consider using @('ld') instead, or in addition; see @(see ld).</p>

 <p>For a general discussion of books, see @(see books).  @('Certify-book') is
 akin to what we have historically called a ``proveall'': all the forms in the
 book are ``proved'' to guarantee their admissibility.  More precisely,
 @('certify-book') (1) reads the forms in the book, confirming that the
 appropriate packages are defined in the certification @(see world); (2) does
 the full admissibility checks on each form (proving termination of recursive
 functions, proving theorems, etc.), checking as it goes that each form is an
 embedded event form (see @(see embedded-event-form)); (3) may roll back the
 logical @(see world) (how far? &mdash; see below) and perform an @(tsee
 include-book) to check for @(tsee local) incompatibilities (see @(see
 local-incompatibility)); (4) writes a @(see certificate) recording not only
 that the book was certified but also recording the @(see command)s necessary
 to recreate the certification @(see world) (so the appropriate packages can be
 defined when the book is included in other @(see world)s) and a @(see
 book-hash) for each of the @(see books) involved (see @(see certificate)); and
 (5) compiles the book if so directed (and then loads the object file in that
 case).</p>

 <p>@('Certify-book') is a macro that returns an @(see error-triple), where
 success is indicated by an error component of @('nil') and has the effect of
 extending the @(see world) with a corresponding @(tsee include-book) event.
 If you don't want the included book's @(see events) in your present @(see
 world), simply execute @(':')@(tsee u).</p>

 <p>Remark.  Step (3) above mentions rolling back the logical @(see world) to
 check for local incompatibilities.  This process is skipped if no @(see local)
 event is encountered.  Otherwise, the world is rolled back through the first
 local event past the boot-strap world &mdash; see @(see local-incompatibility)
 &mdash; before the book is included.  Note that if that first local event is
 in the certification world, then all commands from that event onward will be
 rolled back.  See @(see fast-cert) for a way to skip entirely this process of
 roll-back and check, regardless of local events, but with a risk to soundness.
 End of Remark.</p>

 <p>A utility is provided to assist in debugging failures of @('certify-book');
 see @(see redo-flat).)</p>

 <p>@('Certify-book') requires that the default @(see defun-mode) (see @(see
 default-defun-mode)) be @(':')@(tsee logic) when certification is attempted.
 If the mode is not @(':')@(tsee logic), an error is signaled.</p>

 <p>An error will occur if @('certify-book') has to deal with any uncertified
 book other than the one on which it was called.  For example, if the book
 being certified includes another book, that sub-book must already have been
 certified; that is, that sub-book must have a valid @(see certificate)
 file.</p>

 <p>If you have a certified book that has remained unchanged for some time you
 might well not remember the appropriate @(tsee defpkg)s for it, though they
 are stored in the @(see certificate) file and (by default) also in the
 @('.port') file.  If you begin to change the book, don't throw away its @(see
 certificate) file just because it has become invalid!  It is an important
 historical document until the book is re-certified.  More important, don't
 throw away the @('.port') file, as it will provide the @(see portcullis)
 commands when including the book as an uncertified book; see @(see
 include-book).</p>

 <p>When @('certify-book') is directed to produce a compiled file, it calls the
 Common Lisp function @('compile-file') on the original source file.  This
 creates a compiled file with an extension known to ACL2, e.g., if the book is
 named @('"my-book"') then the source file is @('"my-book.lisp"') and the
 compiled file under GCL will be @('"my-book.o"') while under SBCL it will be
 @('"my-book.fasl"').  The compiled file is then loaded.  When @(tsee
 include-book) is used later on @('"my-book"') it will automatically load the
 compiled file, provided the compiled file has a later write date than the
 source file.  The only effect of such @(see compilation) and loading is that
 the functions defined in the book execute faster.  See @(see guard) for a
 discussion of the issues, and if you want more details about @(see books) and
 compilation, see @(see book-compiled-file).</p>

 <p>When @('certify-book') is directed not to produce a compiled file, it will
 delete any existing compiled file for the book, so as not to mislead @(tsee
 include-book) into loading the now outdated compiled file.  Otherwise,
 @('certify-book') will create a temporary ``expansion file'' to compile,
 obtained by appending the string "@@expansion.lsp" to the end of the book's
 filename.  Remark: Users may ignore that file, which is automatically deleted
 unless @(see state) global variable @(''save-expansion-file') has been set,
 presumably by a system developer, to a non-@('nil') value; see @(see
 book-compiled-file) for more information about this issue, including the role
 of environment variable @('ACL2_SAVE_EXPANSION').</p>

 <p>After execution of a @('certify-book') form, the value of @(tsee
 acl2-defaults-table) is restored to what it was immediately before that
 @('certify-book') form was executed.  See @(see acl2-defaults-table).</p>

 <p>Those who use the relatively advanced features of trust tags (see @(see
 defttag)) and @(tsee make-event) may wish to know how to create a @(see
 certificate) file that avoids dependence on trust tags that are used only
 during @(tsee make-event) expansion.  For this, including documentation of the
 @(':acl2x') and @(':ttagsx') keyword arguments for @('certify-book'), see
 @(see set-write-acl2x).</p>

 <p>This completes the tour through the @(see documentation) of @(see
 books).</p>")

(defxdoc certify-book-debug
  :parents (certify-book books-reference)
  :short "Some possible ways to work around @(tsee certify-book) failures"
  :long "<p>This topic provides some ideas for how to deal with @(tsee
 certify-book) failures.  Ideally, this topic will continue to grow over
 time.</p>

 <p>Stack overflows may show up as follows.</p>

 @({
 ***********************************************
 ************ ABORTING from raw Lisp ***********
 ********** (see :DOC raw-lisp-error) **********
 Error:  Stack overflow on value stack.
 ***********************************************
 })

 <p>When this occurs during book certification, it could be during an attempt
 to handle large objects, in particular by the @(see serialize) writer or by a
 @(see memoize)d version of the check for ``bad'' objects.  These two potential
 causes can be remedied by first evaluating the following forms,
 respectively.</p>

 @({
 (set-serialize-character-system nil state)
 (set-bad-lisp-consp-memoize nil)
 })

 <p>If the large object is in an event in the book under certification, then
 you may need to avoid printing it, as follows.</p>

 @({
 (set-inhibit-output-lst '(proof-tree event))
 })

 <p>Other failures of @('certify-book') may have error messages that point to
 the problem.  When that is not the case, it would be good to explain possible
 workarounds in this topic!</p>")

(defxdoc certify-book!
  :parents (certify-book)
  :short "A variant of @(tsee certify-book)"
  :long "@({
  Examples:
  (certify-book! "my-arith" 3)     ;Certify in a world with 3
                                     ; commands, starting in a world
                                     ; with at least 3 commands.
  (certify-book! "my-arith")       ;Certify in the initial world.

  General Form:
  (certify-book! book-name k compile-flg)
 })

 <p>where @('book-name') is a book filename, @('k') is a nonnegative integer
 used to indicate the ``certification @(see world),'' and @('compile-flg')
 indicates whether you wish to compile the (functions in the) book.</p>

 <p>This @(see command) is identical to @(tsee certify-book), except that the
 second argument @('k') may not be @('t') in @('certify-book!') and if @('k')
 exceeds the current @(see command) number, then an appropriate @(tsee ubt!)
 will be executed first.  See @(see certify-book) and see @(see ubt!).</p>")

(defxdoc change
  :parents (defrec acl2-built-ins)
  :short "Mutator macro for @(see defrec) structures."
  :long "<p>The @('change') macro is built into ACL2, and allows you to
 "modify" instances of structures that have been introduced with @(see
 defrec).  Of course, since ACL2 is applicative, the original structure is not
 actually changed&mdash;instead, a new structure is constructed, copying some
 fields from the original structure and installing new values for other
 fields.</p>

 <p>For instance, suppose we first use @(see make) to create an employee
 structure, e.g.,:</p>

 @({
    (defconst *jimmy* (make employee :name "Jimmy"
                                     :salary 0
                                     :position "Unpaid Intern")
 })

 <p>Then we can use @('change') to mutate this structure, e.g.,:</p>

 @({
     (change employee *jimmy* :salary 300000
                              :position "Vice President")
 })

 <p>Produces a new @('employee') structure where the @('name') is still
 "Jimmy", but where the @('salary') and @('position') have been updated to
 300000 and "Vice President", respectively.</p>

 <p>See @(see defrec) for more information.</p>")

(defxdoc char
  :parents (strings characters acl2-built-ins)
  :short "The @(see nth) element (zero-based) of a string"
  :long "<p>@('(Char s n)') is the @('n')th element of @('s'), zero-based.  If
 @('n') is greater than or equal to the length of @('s'), then @('char')
 returns @('nil').</p>

 <p>@('(Char s n)') has a @(see guard) that @('n') is a non-negative integer
 and @('s') is a @(tsee stringp).</p>

 <p>@('Char') is a Common Lisp function.  See any Common Lisp documentation for
 more information.</p>

 @(def char)")

(defxdoc char-code
  :parents (characters numbers acl2-built-ins)
  :short "The numeric code for a given character"
  :long "<p>This function maps a character to its code, for example:
  @('(char-code #\A)') evaluates to @('65').  See @(tsee code-char) for a sort
  of inverse function, which maps a code to the corresponding character.</p>

 <p>Completion Axiom (@('completion-of-char-code')):</p>

 @({
  (equal (char-code x)
         (if (characterp x)
             (char-code x)
           0))
 })

 <p>@(see Guard) for @('(char-code x)'):</p>

 @({
  (characterp x)
 })

 <p>This function maps all non-characters to @('0').</p>")

(defxdoc char-downcase
  :parents (characters acl2-built-ins)
  :short "Turn upper-case @(see characters) into lower-case @(see characters)"
  :long "<p>@('(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.</p>

 <p>The @(see guard) for @('char-downcase') states that its argument is a
 character.</p>

 <p>@('Char-downcase') is a Common Lisp function.  See any Common Lisp
 documentation for more information.  Note that the value returned may depend
 on the host Lisp; see @(see soundness), specifically Example 1 in the Section,
 &ldquo;Examples of divergence among Lisp implementations&rdquo;.</p>

 @(def char-downcase)")

(defxdoc char-equal
  :parents (characters acl2-built-ins)
  :short "Character equality without regard to case"
  :long "<p>For @(see 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.</p>

 <p>The @(see guard) on @('char-equal') states that its arguments are both
 @(see characters).</p>

 <p>@('Char-equal') is a Common Lisp function.  See any Common Lisp
 documentation for more information.  Note that the value returned may depend
 on the host Lisp; see @(see soundness), specifically Example 1 in the Section,
 &ldquo;Examples of divergence among Lisp implementations&rdquo;.</p>

 @(def char-equal)")

(defxdoc char-upcase
  :parents (characters acl2-built-ins)
  :short "Turn lower-case @(see characters) into upper-case @(see characters)"
  :long "<p>@('(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.</p>

 <p>The @(see guard) for @('char-upcase') states that its argument is a
 character.</p>

 <p>@('Char-upcase') is a Common Lisp function.  See any Common Lisp
 documentation for more information.  Note that the value returned may depend
 on the host Lisp; see @(see soundness), specifically Example 1 in the Section,
 &ldquo;Examples of divergence among Lisp implementations&rdquo;.</p>

 @(def char-upcase)")

(defxdoc char<
  :parents (characters acl2-built-ins)
  :short "Less-than test for @(see characters)"
  :long "<p>@('(char< x y)') is true if and only if the character code of
 @('x') is less than that of @('y').  See @(see char-code).</p>

 <p>The @(see guard) for @('char<') specifies that its arguments are @(see
 characters).</p>

 <p>@('Char<') is a Common Lisp function.  See any Common Lisp documentation
 for more information.</p>

 @(def char<)")

(defxdoc char<=
  :parents (characters acl2-built-ins)
  :short "Less-than-or-equal test for @(see characters)"
  :long "<p>@('(char<= x y)') is true if and only if the character code of
 @('x') is less than or equal to that of @('y').  See @(see char-code).</p>

 <p>The @(see guard) for @('char<=') specifies that its arguments are @(see
 characters).</p>

 <p>@('Char<=') is a Common Lisp function.  See any Common Lisp documentation
 for more information.</p>

 @(def char<=)")

(defxdoc char>
  :parents (characters acl2-built-ins)
  :short "Greater-than test for @(see characters)"
  :long "<p>@('(char> x y)') is true if and only if the character code of
 @('x') is greater than that of @('y').  See @(see char-code).</p>

 <p>The @(see guard) for @('char>') specifies that its arguments are @(see
 characters).</p>

 <p>@('Char>') is a Common Lisp function.  See any Common Lisp documentation
 for more information.</p>

 @(def char>)")

(defxdoc char>=
  :parents (characters acl2-built-ins)
  :short "Greater-than-or-equal test for @(see characters)"
  :long "<p>@('(char>= x y)') is true if and only if the character code of
 @('x') is greater than or equal to that of @('y').  See @(see char-code).</p>

 <p>The @(see guard) for @('char>=') specifies that its arguments are @(see
 characters).</p>

 <p>@('Char>=') is a Common Lisp function.  See any Common Lisp documentation
 for more information.</p>

 @(def char>=)")

(defxdoc character-alistp
  :parents (characters alists acl2-built-ins)
  :short "Recognizer for association lists with characters as keys"
  :long "<p>@('(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 @(tsee
 characterp).</p>

 @(def character-alistp)")

(defxdoc character-encoding
  :parents (io)
  :short "How bytes are parsed into characters"
  :long "<p>When the Common Lisp reader comes across bytes in a file or at the
 terminal, they are parsed into characters.  The simplest case is when each
 byte that is read is a standard character (see @(see standard-char-p)).  It is
 actually quite common that each byte that is read corresponds to a single
 character.  The parsing of bytes into characters is based on a <i>character
 encoding</i>, that is, a mapping that associates one or more bytes with each
 legal character.</p>

 <p>In order to help guarantee the portability of files (including @(see
 books)), ACL2 installs a common character encoding for reading files, often
 known as ISO-8859-1 or Latin-1.  For some host Lisps this character encoding
 is also used for reading from the terminal; but, sadly, this may not hold for
 all host Lisps, and may not even be possible for some of them.</p>

 <p>The use of the above encoding could in principle cause problems if one's
 editor produces files using an encoding other than ISO-8859-1, at least if one
 uses non-standard characters.  In particular, the default Emacs buffer
 encoding may be utf-8.  If your file has non-standard characters, then in
 Emacs you can evaluate the form</p>

 @({
  (setq save-buffer-coding-system 'iso-8859-1)
 })

 <p>before saving the buffer into a file.  This will happen automatically for
 users who load distributed file @('emacs-acl2.el') (from a suitable directory;
 see @(see emacs)) into their Emacs sessions.</p>

 <p>For an example of character encodings in action, see the community book
 @('books/misc/character-encoding-test.lisp').</p>")

(defxdoc character-listp
  :parents (characters lists acl2-built-ins)
  :short "Recognizer for a true list of characters"
  :long "<p>The predicate @('character-listp') tests whether its argument is a
 true list of @(see characters).</p>

 @(def character-listp)")

(defxdoc characterp
  :parents (characters acl2-built-ins)
  :short "Recognizer for @(see characters)"
  :long "<p>@('(characterp x)') is true if and only if @('x') is a character.
 Note that ACL2 supports characters with ASCII codes between 0 and 255.  See
 also @(see code-char) and @(see char-code).</p>")

(defxdoc characters
  :parents (programming)
  :short "Characters in ACL2 and operations on them"
  :long "<p>ACL2 accepts 256 distinct characters, which are the characters
 obtained by applying the function @(tsee code-char) to each integer from
 @('0') to @('255').  Among these, Common Lisp designates certain ones as
 <i>standard characters</i>, 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
 @(tsee defconst) @('*standard-chars*').</p>

 <p>To be more precise, Common Lisp does not specify the precise relationship
 between @(tsee 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, Rubout, and Return correspond to characters with respective
 @(tsee char-code)s @('32'), @('9'), @('10'), @('12'), @('127'), and
 @('13').</p>

 <p>@(tsee Code-char) has an inverse, @(tsee char-code).  Thus, when @(tsee
 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').</p>

 <p>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.</p>

 <p><i>The Character Reader</i></p>

 <p>ACL2 supports the `@('#\')' notation for characters provided by Common
 Lisp, with some restrictions.  First of all, for every character @('c'), the
 notation</p>

 @({
  #\c
 })

 <p>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:</p>

 @({
  "  '  (  )  ;  `  ,
 })

 <p>Other than the notation above, ACL2 accepts alternate notation for five
 characters.</p>

 @({
  #\Space
  #\Tab
  #\Newline
  #\Page
  #\Rubout
  #\Return
 })

 <p>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 ISO-8859-1, even though we don't provide
 @('#\') syntax for entering characters other than that described above.</p>

 <p>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.</p>")

(defxdoc check-vars-not-free
  :parents (macros)
  :short "Avoid variable capture in macro calls"
  :long "<p>@('Check-vars-not-free') is a macro that is useful for avoiding
 capture of variables in macro calls.  We explain using a running example,
 after which we give a precise explanation (at the end of this documentation
 topic).  These definitions are rather contrived but are designed to illustrate
 how @('check-vars-not-free') can be useful.</p>

 @({
 (defmacro has-length (x n)
   `(let ((k (len ,x)))
      (equal k ,n)))
 (defun f1 (u v)
   (and (natp v)
        (has-length u (* 2 v))))
 (defun f2 (lst k)
   (and (natp k)
        (has-length lst (* 2 k))))
 })

 <p>One might expect @('f1') and @('f2') to be the same function, since the
 only change seems to be from the choices of formal parameters.  However,
 consider these evaluations.</p>

 @({
 ACL2 !>(f1 '(a b c d e f) 3)
 T
 ACL2 !>(f2 '(a b c d e f) 3)
 NIL
 ACL2 !>
 })

 <p>The problem becomes clear if we expand the macro call in the body of
 @('f2').</p>

 @({
 ACL2 !>:trans1 (has-length lst (* 2 k))
  (LET ((K (LEN LST))) (EQUAL K (* 2 K)))
 ACL2 !>
 })

 <p>We see that when expanding the call of the macro @('has-length') in the
 body of @('f2'), the substitution of @('(* 2 k)') for @(',n') causes @('k') to
 be``captured'' by the binding of @('k') to @('(len lst)').</p>

 <p>The macro @('check-vars-not-free') is designed to enforce that no such
 capture takes place.  An improved definition of @('has-length') is as
 follows, since it insists that the variable @('k') must not appear in the term
 that replaces @(',n').</p>

 @({
 (defmacro has-length (x n)
   `(let ((k (len ,x)))
      (equal k (check-vars-not-free (k) ,n))))
 })

 <p>Now, the attempt to define @('f2') as above causes an error.</p>

 @({
 ACL2 !>(defun f2 (lst k)
    (and (natp k)
         (has-length lst (* 2 k))))


 ACL2 Error in ( DEFUN F2 ...):  CHECK-VARS-NOT-FREE failed:
 It is forbidden to use K in (BINARY-* '2 K).  Note:  this error occurred
 in the context (CHECK-VARS-NOT-FREE (K) (* 2 K)).


 Summary
 Form:  ( DEFUN F2 ...)
 Rules: NIL
 Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)

 ACL2 Error in ( DEFUN F2 ...):  See :DOC failure.

 ******** FAILED ********
 ACL2 !>
 })

 <p>The error message shows that the check performed by
 @('check-vars-not-free') has failed, because the variable @('k') occurs in the
 expression @('(* 2 k)').  More precisely, what is checked is that @('k') does
 not occur in the translation to a @(see term) of the expression @('(* 2 k)'),
 namely, @('(binary-* '2 k)').</p>

 <p>The general form of a call of @('check-vars-not-free') is</p>

 @({
 (check-vars-not-free (var_1 ... var_n) expr)
 })

 <p>where @('var_1'), ..., @('var_n') are variables and @('expr') is an
 expression.  This call is equivalent to @('expr') &mdash; indeed, there is no
 effect on the code generated when using this call in place of @('expr')
 &mdash; but ACL2 requires that the indicated variables do not occur free in
 the translation of @('expr') to a term.</p>")

(defxdoc checkpoint-summary-limit
  :parents (summary set-gag-mode)
  :short "Control printing of key checkpoints upon a proof's failure"
  :long "<p>See @(see set-checkpoint-summary-limit) for a discussion of the
 checkpoint-summary-limit.  Evaluation of the form
 @('(checkpoint-summary-limit)') produces the current checkpoint-summary-limit,
 and can be invoked with the keyword hack (see @(see keyword-commands)).  For
 example:</p>

 @({
 ACL2 !>:checkpoint-summary-limit
 (NIL . 3)
 ACL2 !>
 })")

(defxdoc checksum
  :parents (certificate)
  :short "Assigning ``often unique'' integers to files and objects"
  :long "<p>See @(see book-hash) for a discussion of how ACL2 can use checksums
 (though not by default) to increase security in the @(see books)
 mechanism.</p>

 <p>A <i>checksum</i> 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 @(see characters) in the printed representation.</p>

 <p>Ideally, you would like the checksum 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
 checksum (which is relatively small) and when an object is presented to you
 and alleged to be the special one you could compute its checksum and see if
 indeed it was.  Alas, there are many more objects than checksums (after all,
 each checksum is an object, and then there's @('t')).  So you try to design a
 checksum algorithm that maps similar looking objects far apart, in the hopes
 that corruptions and counterfeits &mdash; which appear to be similar to the
 object &mdash; have different checksums.  Nevertheless, the best you can do is
 a many-to-one map.  If an object with a different checksum is presented, you
 can be positive it is not the special object.  But if an object with the same
 checksum is presented, you have no grounds for positive identification.</p>

 <p>The basic checksum algorithm in ACL2 is called @('check-sum-obj'), which
 computes the checksum 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.</p>")

(defxdoc checkpoint-forced-goals
  :parents (proof-tree)
  :short "Cause forcing goals to be checkpointed in proof trees"
  :long "@({
  Example forms:
  (checkpoint-forced-goals t)
  (checkpoint-forced-goals nil)
 })

 <p>Also see @(see proof-tree).</p>

 <p>By default, goals are not marked as checkpoints by a proof tree display (as
 described elsewhere; see @(see proof-tree)) merely because they @(see force)
 some hypotheses, thus possibly contributing to a forcing round.  However, some
 users may want such behavior, which will occur once the command
 @('(checkpoint-forced-goals') @('t')) has been executed.  To return to the
 default behavior, use the command @('(checkpoint-forced-goals nil)').</p>")

(defxdoc clause
  :parents (miscellaneous)
  :short "A representation of prover goals"
  :long "<p>In ACL2, a <i>clause</i> is a list of @(see term)s, and the meaning
 of a clause is the ACL2 disjunction of those terms where a term @('p') is
 considered ``false'' if ``@('p') = @('nil')'' and is true otherwise.  The
 elements of a clause are called ``literals,'' even though they are just terms.
 For example the goal @('(IMPLIES (AND p q) r)') is internally represented as
 the clause @('((NOT p) (NOT q) r)').  The literals of that clause are the
 terms @('(NOT p)'), @('(NOT q)'), and @('r').</p>

 <p>The ACL2 prover acts on clauses: a goal is represented as a clause, and
 each of the resulting subgoals is represented as a clause.  Thus, the terms
 (literals) in a clause are all translated (see @(see term)).</p>

 <p>To be precise, suppose that @('(L1 .. Lk M)') is a clause containing at
 least two literals.  ACL2 proof output displays that clause as an implication;
 this is called &ldquo;prettyifying a clause&rdquo;.  Below, @('~Li') denotes
 the <i>negation</i> of @('Li') in the following sense: if @('Li') is of the
 form @('(NOT P)') then @('~Li') designates @('P'), and otherwise @('~Li')
 designates @('(NOT Li)').</p>

 <blockquote>
 <p><b>Prettyifying a clause with at least two literals</b></p>
 @({
 (L1 .. Lk M)
 })
 <p>transforms it to the term</p>
 @({
 (IMPLIES (AND ~L1 ~L2 ... ~Lk)
          M).
 })
 </blockquote>

 <p>Of course, the disjunction represented by the clause is propositionally
 equivalent to the resulting call of @('IMPLIES').</p>

 <p>It is sometimes helpful to understand that ACL2's proof processes all
 operate on clauses.  In particular, proof output &mdash; obtained when @(see
 gag-mode) is turned off or when using @(':')@(tsee pso) or related utilities
 &mdash; may include a parenthetical remark as follows.  <b>WARNING</b>: This
 parenthetical remark is printed only by the main simplifier, not by the
 preprocessor (see @(see simple)).</p>

 @({
 This simplifies (dropping false conclusion; see :DOC clause), using ....
 })

 <p>What this remark signifies is that the last literal of the clause is false
 in at least one subgoal, and therefore does not appear in it (even in
 rewritten form).  Let's see how that works with the following example.</p>

 @({
 (defstub foo (x) t)
 (defaxiom foo-consp (implies (consp x) (foo x)))
 (set-gag-mode nil)
 (thm (implies (and (consp x) (natp (car x))) (not (foo x))))
 })

 <p>The proof attempt starts as follows.</p>

 @({
 ACL2 !>(thm (implies (and (consp x) (natp (car x))) (not (foo x))))

 By the simple :definition NATP we reduce the conjecture to

 Goal'
 (IMPLIES (AND (CONSP X)
               (INTEGERP (CAR X))
               (<= 0 (CAR X)))
          (NOT (FOO X))).

 This simplifies (dropping false conclusion; see :DOC clause), using
 the :rewrite rule FOO-CONSP, to

 Goal''
 (IMPLIES (AND (CONSP X) (INTEGERP (CAR X)))
          (< (CAR X) 0)).
 })

 <p>The change from @('Goal'') to @('Goal''') may be jarring because the
 &ldquo;conclusion&rdquo; &mdash; the second argument of the displayed
 @('IMPLIES') call &mdash; has changed drastically.  Let's analyze this change
 from the perspective of the goals printed; then we'll look at it from the
 perspective of clauses.</p>

 <p>A moment's reflection shows that because of the rule @('FOO-CONSP'),
 @('Goal'') is equivalent to</p>

 @({
 (IMPLIES (AND (CONSP X)
               (INTEGERP (CAR X))
               (<= 0 (CAR X)))
          NIL).
 })

 <p>And a little more reflection shows that the term above is propositionally
 equivalent to @('Goal''') above.</p>

 <p>But this may make more sense if we consider the clauses on which the prover
 operated.  Here are the clauses for @('Goal'') and @('Goal'''); the
 corresponding @('IMPLIES') terms displayed above are obtained by prettyifying
 the respective clauses (in the sense of &ldquo;prettyifying&rdquo; discussed
 above).</p>

 @({
 Goal'
 ((NOT (CONSP X))
  (NOT (INTEGERP (CAR X)))
  (< (CAR X) '0)
  (NOT (FOO X)))

 Goal''
 ((NOT (CONSP X))
  (NOT (INTEGERP (CAR X)))
  (< (CAR X) '0))
 })

 <p>For each of these clauses, the third literal, @('(< (CAR X) '0)'), is just
 the negation of the (untranslated) @(see term), @('(<= 0 (CAR X))'), shown in
 the prover output.</p>

 <p>Recall that a clause represents the disjunction of its literals.  Since the
 last literal of @('Goal''), @('(NOT (FOO X))'), rewrote to @('NIL') using the
 rule @('FOO-CONSP'), it was dropped when creating @('Goal'''): after all,
 @('(OR P NIL)') is propositionally equivalent to @('P').  So in @('Goal''')
 the last literal is @('(< (CAR X) '0)').  Therefore, the conclusion of each
 @('IMPLIES') term obtained by prettyifying the clause has changed from
 @('(NOT (FOO X))') to @('(< (CAR X) '0)').</p>

 <p>Finally, note that although &ldquo;dropping false conclusion&rdquo;
 signifies that the conclusion was dropped in at least one subgoal, if however
 there are at least two subgoals then it might not be dropped in all of them.
 Consider the following variant of the earlier example.</p>

 @({
 (defstub foo (x) t)
 (defaxiom foo-consp (implies (consp x) (foo x)))
 (set-gag-mode nil)
 (defstub bar (x) t)
 ; The proof fails for the following event (not important here).
 (thm (implies (and (or (bar x) (consp x)) (natp (car x)))
               (not (foo x)))
      :otf-flg t)
 })

 <p>The output includes the following.</p>

 @({
 Goal'
 (IMPLIES (AND (OR (BAR X) (CONSP X))
               (INTEGERP (CAR X))
               (<= 0 (CAR X)))
          (NOT (FOO X))).

 This simplifies (dropping false conclusion; see :DOC clause), using
 the :rewrite rule FOO-CONSP, to the following two conjectures.

 Subgoal 2
 (IMPLIES (AND (BAR X)
               (INTEGERP (CAR X))
               (<= 0 (CAR X)))
          (NOT (FOO X))).

 [[.. output elided ..]]

 Subgoal 1
 (IMPLIES (AND (CONSP X) (INTEGERP (CAR X)))
          (< (CAR X) 0)).
 })

 <p>We see that the conclusion was false, hence dropped, in Subgoal 1, but
 remained in Subgoal 2.</p>")

(defxdoc clause-identifier
  :parents (goal-spec)
  :short "The internal form of a @(see goal-spec)"
  :long "<p>To each goal-spec, @('str'), there corresponds a @(see
 clause)-identifier produced by @('(parse-clause-id str)').  For example,</p>

 @({
  (parse-clause-id "[2]Subgoal *4.5.6/7.8.9'''")
 })

 <p>returns @('((2 4 5 6) (7 8 9) . 3)').</p>

 <p>The function @('string-for-tilde-@-clause-id-phrase') inverts
 @('parse-clause-id') in the sense that given a clause identifier it returns
 the corresponding goal-spec.</p>

 <p>As noted in the documentation for @(see goal-spec), each clause printed in
 the theorem prover's proof attempt is identified by a name.  When these names
 are represented as strings they are called ``goal specs.''  Such strings are
 used to specify where in the proof attempt a given hint is to be applied.  The
 function @('parse-clause-id') converts goal-specs into clause identifiers,
 which are cons-trees containing natural numbers (and if @(':OR') @(see hints)
 are used, they may also contain symbols of the form @('Dn') where @('n') is a
 natural number, e.g., @('D23').)</p>

 <p>Examples of goal-specs and their corresponding clause identifiers are shown
 below.</p>

 @({
               parse-clause-id
                     -->

  "Goal"                       ((0) NIL . 0)
  "Subgoal 3.2.1'"             ((0) (3 2 1) . 1)
  "[2]Subgoal *4.5.6/7.8.9'''" ((2 4 5 6) (7 8 9) . 3)

                     <--
        string-for-tilde-@-clause-id-phrase
 })

 <p>The caar of a clause id specifies the forcing round, the cdar specifies the
 goal being proved by induction, the cadr specifies the particular subgoal, and
 the cddr is the number of primes in that subgoal.</p>

 <p>Internally, the system maintains clause ids, not goal-specs.  The system
 prints clause ids in the form shown by goal-specs.  When a goal-spec is used
 in a hint, it is parsed (before the proof attempt begins) into a clause id.
 During the proof attempt, the system watches for the clause id and uses the
 corresponding hint when the id arises.  (Because of the expense of creating
 and garbage collecting a lot of strings, this design is more efficient than
 the alternative.)</p>")

(defxdoc clause-processor
  :parents (rule-classes)
  :short "Make or apply a @(':clause-processor') rule (goal-level simplifier)"
  :long "<p>See @(see rule-classes) for a general discussion of rule classes,
 including how they are used to build rules from formulas and a discussion of
 the various keywords in a rule class description.</p>

 <p>We will introduce clause-processor rules by way of the following example.
 But note that the clause-processor utility is more general than this example
 may suggest; for example, the second argument of @('evl0') in the hypothesis
 need not be the same as its second argument in the conclusion.</p>

 @({
  ; Example (which we'll return to, below):
  (defthm correctness-of-note-fact-clause-processor
    (implies (and (pseudo-term-listp cl)
                  (alistp a)
                  (evl0 (conjoin-clauses
                         (note-fact-clause-processor cl term))
                        a))
             (evl0 (disjoin cl) a))
    :rule-classes :clause-processor)
 })

 <p>We begin this documentation with an introduction, focusing on the example
 above, and then conclude with a detailed general discussion of
 clause-processor rules.  You might find it most useful simply to look at the
 examples in community books directory @('books/clause-processors/'); see file
 @('Readme.lsp') in that directory.</p>

 <p>Also see @(see define-trusted-clause-processor) for documentation of an
 analogous utility that does not require the clause-processor to be proved
 correct.  But please read the present documentation before reading about that
 utility.  Both utilities designate functions as ``clause-processors''.  Such
 functions must be executable &mdash; hence not constrained by virtue of being
 introduced in the @(see signature) of an @(tsee encapsulate) &mdash; and must
 respect @(see stobj), @(see df), and output arity restrictions.  For example,
 something like @('(car (mv ...))') is illegal; also see @(see signature).</p>

 <h4>INTRODUCTION</h4>

 <p>A @(':clause-processor') rule installs a simplifier at the level of goals,
 where a goal is represented as a @(see clause): a list of @(see term)s that is
 implicitly viewed as a disjunction (the application of @(tsee OR)).  For
 example, if ACL2 prints a goal in the form @('(implies (and p q) r)'), then
 the clause might be the one-element list containing the internal
 representation of this term &mdash; @('(implies (if p q 'nil) r)') &mdash; but
 more likely, the corresponding clause is @('((not p) (not q) r)').  Note that
 the members of a clause are <i>translated</i> terms; see @(see term) and
 @(tsee termp).  For example, they do not contain calls of the macro @('AND'),
 and constants are quoted.  The result of running a clause-processor must be a
 list of legal clauses; see @(see meta) for a discussion of translated terms,
 and for related discussion about ``forbidden'' function symbols, @(see
 set-skip-meta-termp-checks).</p>

 <p>The recognizer for a clause is the function @(tsee term-listp) and the
 recognizer for a list of clauses is @(tsee term-list-listp).</p>

 <p>Note that clause-processor simplifiers are similar to metafunctions, and
 similar efficiency considerations apply.  See @(see meta), in particular the
 discussion on how to ``make a metafunction maximally efficient.''</p>

 <p>Unlike rules of class @(':')@(tsee meta), rules of class
 @(':clause-processor') must be applied by explicit @(':clause-processor')
 @(see hints); they are not applied automatically (unless by way of computed
 hints; see @(see computed-hints)).  But @(':clause-processor') rules can be
 useful in situations for which it is more convenient to code a simplifier that
 manipulates the entire goal clause rather than individual subterms of terms in
 the clause.</p>

 <p>We begin with a simple illustrative example: a clause-processor that
 assumes an alleged fact (named @('term') in the example) and creates a
 separate goal to prove that fact.  We can extend the hypotheses of the current
 goal (named @('cl') in the example) with a term by adding the negation of that
 term to the clause (disjunctive) representation of that goal.  So the
 following returns a list of two clauses: the result of adding @('term') as a
 hypothesis to the input clause, as just described, and a second clause
 consisting only of that term.  This list of two clauses can be viewed as the
 conjunction of the first clause and the second clause (where again, each
 clause is viewed as a disjunction).</p>

 @({
  (defun note-fact-clause-processor (cl term)
    (declare (xargs :guard t)) ; optional, for better efficiency
    (list (cons (list 'not term)
                cl)
          (list term)))
 })

 <p>As with @(':')@(tsee meta) rules, we need to introduce a suitable
 evaluator; see @(see defevaluator) if you want details.  Since we expect to
 reason about the function @(tsee NOT), because of its role in
 @('note-fact-clause-processor') as defined above, we include @('NOT') in the
 set of functions known to this evaluator.  We also include @('IF'), as is
 often a good idea.</p>

 @({
  (defevaluator evl0 evl0-list
    ((not x) (if x y z)))
 })

 <p>ACL2 can now prove the following theorem automatically.  (This is the
 example displayed at the outset of this @(see documentation) topic.)  Of
 course, @(':clause-processor') rules about clause-processor functions less
 trivial than @('note-fact-clause-processor') may require lemmas to be proved
 first!  The function @('disjoin') takes a clause and returns its disjunction
 (the result of applying @(tsee OR) to its members), and @('conjoin-clauses')
 applies @('disjoin') to every element of a given list of clauses and then
 conjoins (applies @('AND')) to the corresponding list of resulting terms.</p>

 @({
  (defthm correctness-of-note-fact-clause-processor
    (implies (and (pseudo-term-listp cl)
                  (alistp a)
                  (evl0 (conjoin-clauses
                         (note-fact-clause-processor cl term))
                        a))
             (evl0 (disjoin cl) a))
    :rule-classes :clause-processor)
 })

 <p>Now let us submit a silly but illustrative example theorem to ACL2, to show
 how a corresponding @(':clause-processor') hint is applied.  The hint says to
 apply the clause-processor function, @('note-fact-clause-processor'), to the
 current goal clause and a ``user hint'' as the second argument of that
 function, in this case @('(equal a a)').  Thus, a specific variable,
 @('clause'), is always bound to the current goal clause for the evaluation of
 the @(':clause-processor') hint, to produce a list of clauses.  Since two
 subgoals are created below, we know that this list contained two clauses.
 Indeed, these are the clauses returned when @('note-fact-clause-processor') is
 applied to two arguments: the current clause, which is the one-element list
 @('((equal (car (cons x y)) x))'), and the user hint, @('(equal a a)').</p>

 @({
  ACL2 !>(thm (equal (car (cons x y))
                     x)
              :hints
              (("Goal"
                :clause-processor
                (note-fact-clause-processor clause '(equal a a)))))

  [Note:  A hint was supplied for the goal above.  Thanks!]

  We now apply the verified :CLAUSE-PROCESSOR function NOTE-FACT-CLAUSE-
  PROCESSOR to produce two new subgoals.

  Subgoal 2
  (IMPLIES (EQUAL A A)
           (EQUAL (CAR (CONS X Y)) X)).

  But we reduce the conjecture to T, by the :executable-counterpart of
  IF and the simple :rewrite rule CAR-CONS.

  Subgoal 1
  (EQUAL A A).

  But we reduce the conjecture to T, by primitive type reasoning.

  Q.E.D.

  Summary
  Form:  ( THM ...)
  Rules: ((:EXECUTABLE-COUNTERPART IF)
          (:EXECUTABLE-COUNTERPART NOT)
          (:FAKE-RUNE-FOR-TYPE-SET NIL)
          (:REWRITE CAR-CONS))
  Warnings:  None
  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)

  Proof succeeded.
  ACL2 !>
 })

 <p>That concludes our introduction to clause-processor rules and hints.  We
 turn now to detailed documentation.</p>

 <h4>DETAILED DOCUMENTATION</h4>

 <p>The @(see signature) of a clause-processor function, @('CL-PROC'), must
 have one of the following forms.  Here, each @('st_i') is a @(see stobj)
 (possibly @(tsee state)) while the other parameters and results are not stobjs
 (see @(see stobj)).  Note that there need not be input stobjs in [3] &mdash;
 i.e., @('k') can be 0 &mdash; and even if there are, there need not be output
 stobjs.  In most ways [3] and [3+] are treated similarly; see @(see
 make-summary-data) for a discussion of the form of @('d') in [3+] and, more
 generally, for how [3+] differs from [3] by enhancing the @(see summary).</p>

 @({
  [1]  ((CL-PROC cl) => cl-list)

  [2]  ((CL-PROC cl hint) => cl-list)

  [3]  ((CL-PROC cl hint st_1 ... st_k) => (mv erp cl-list st_i1 ... st_in))

  [3+] ((CL-PROC cl hint st_1 ... st_k) => (mv erp cl-list st_i1 ... st_in d))
 })

 <p>We call @('cl-list') the <i>clauses-result</i>.  In [3] and [3+], we think
 of the first component of the result as an error flag.  Indeed, a proof will
 instantly abort if that error flag is not @('nil').</p>

 <p>We next discuss the legal forms of @(':clause-processor') rules, followed
 below by a discussion of @(':clause-processor') @(see hints).  In the
 discussion below, we use lower-case names to represent specific symbols, for
 example @('implies'), and also to represent @(see stobj) names; and we use
 upper-case names to represent arbitrary pieces of syntax (which we will
 describe), for example, @('CL').</p>

 <p>If a @(':')@(tsee rule-classes) specification includes
 @(':clause-processor'), then the corresponding term must have the following
 form.  (Additional ``meta-extract'' hypotheses, not shown or discussed below,
 may be included as desired in order to use facts from the logical @(tsee
 world) to help prove the rule; see @(see meta-extract) for explanation of this
 advanced feature.)</p>

 @({
  ; General Form (omitting possible meta-extract hypotheses)
  (implies (and (pseudo-term-listp CL)
                (alistp A)
                (EVL (conjoin-clauses <CL-LIST>)
                      B))
           (EVL (disjoin CL) A))
 })

 <p>Here @('EVL') is a known evaluator; @('CL') and @('A') are distinct
 non-stobj variables; and @('<CL-LIST>') is an expression representing the
 clauses returned by the clause-processor function @('CL-PROC'), whose form
 depends on the @(see signature) of that function, as follows.  Typically
 @('B') is @('A'), but it can be any term (useful when generalization is
 occurring; see the example ``Test generalizing alist'' in community book
 @('books/clause-processors/basic-examples.lisp')).  For cases [1] and [2]
 above, @('<CL-LIST>') is of the form @('(CL-PROC CL)') or @('(CL-PROC CL
 HINT)'), respectively, where in the latter case @('HINT') is a non-stobj
 variable distinct from the variables @('CL') and @('A').  For cases [3] and
 [3+], @('<CL-LIST>') is the result of wrapping the function
 @('clauses-result') around a call of @('CL-PROC'):</p>

 @({
  (clauses-result (CL-PROC CL HINT ...))
 })

 <p>Logically, @('clauses-result') returns the @(tsee cadr) if the @(tsee car)
 is @('NIL'), and otherwise (for the error case) returns a list containing the
 empty (false) clause.  So in the non-error case, @('clauses-result') picks out
 the second result, denoted @('cl-list') in [3] and [3+] above, and in the
 error case the implication above trivially holds.</p>

 <p>In the above theorem, we are asked to prove @('(EVL (disjoin CL) A)')
 assuming that the conjunction of all clauses produced by the clause processor
 evaluates to a non-@('nil') value under some alist @('B').  In fact, we can
 choose @('B') so as to allow us to assume evaluations of the generated clauses
 over many different alists.  This technique is discussed in the community book
 @('books/clause-processors/multi-env-trick.lisp'), which introduces some
 macros that may be helpful in accomplishing proofs of this type.</p>

 <p>The clause-processor function, @('CL'), must have a guard that ACL2 can
 trivially prove from the hypotheses that the first argument of @('CL') is
 known to be a @('pseudo-term-listp') and any @(see stobj) arguments are
 assumed to satisfy their stobj predicates.</p>

 <p>Next we specify the legal forms for @(':clause-processor') @(see hints).
 The basic form is @(':clause-processor TERM'), such that the translation of
 @('TERM') to a legal ACL2 term yields a call of a clause-processor function
 @('(CL-PROC clause)') or @('(CL-PROC clause HINT ...)'), where @('HINT') is a
 term whose only non-stobj free variable (if any) is the symbol, @('clause').
 Note that the first argument of the call is literally the variable,
 @('clause').  Recall that at the time the :clause-processor hint is applied to
 the clausal form @('CL') of the current subgoal, @('clause') is bound to
 @('CL'); moreover, any stobj names will be bound to the corresponding
 stobjs.</p>

 <p>But there are two additional general forms for @(':clause-processor')
 hints, which may viewed as abbreviations for the basic form discussed above.
 The first additional general form, which we call the ``@(':function') form'',
 includes the following two classes of expressions.</p>

 @({
 :clause-processor (:function F)
 :clause-processor (:function F :hint HINT)
 })

 <p>The first of these @(':function') forms abbreviates the following hint,
 where either @('F') is a macro-alias for the function symbol @('CL-PROC') (see
 @(see add-macro-alias)), and otherwise @('CL-PROC') is just the function
 symbol @('F').</p>

 @({
 :clause-processor (CL-PROC clause)
 })

 <p>Similarly the second of the @(':function') forms above abbreviates the
 following, where @('CL-PROC') is as above and the output signature of
 @('CL-PROC') is @('(nil nil st_1 ... st_k)').</p>

 @({
 :clause-processor (CL-PROC clause HINT st_1 ... st_k)
 })

 <p>Besides the ``@(':function') form'', there is one more additional general
 form for @(':clause-processor') hint: a symbol, as follows.</p>

 @({
 :clause-processor F
 })

 <p>This expands to a basic form as follows, depending on @('F').</p>

 <ul>

 <li>If @('F') is a macro with one required argument or a function symbol with
 one argument:<br/>
 @(':clause-processor (F clause)')</li>

 <li>If @('F') is a macro with two required arguments or a function symbol with
 two arguments:<br/>
 @(':clause-processor (F clause nil)')</li>

 <li>If @('F') is a function symbol with inputs of the form [3] or [3+] above,
 that is, with input signature @('(nil nil st_1 ... st_k)'):<br/>
 @(':clause-processor (F clause nil st_1 ... st_k)')</li>

 </ul>

 <p>For examples of these syntactic forms, see community book
 @('books/clause-processors/basic-examples.lisp')).  We turn now to discussion
 of when a @(':clause-processor') hint causes an abort.</p>

 <p>A @(':clause-processor') hint causes the proof to abort if the
 clauses-result is not a list of clauses, i.e., a list of (translated) @(see
 term) lists in the current logical @(see world).  This test is done explicitly
 every time a clause processor is run unless a @(':')@(tsee
 well-formedness-guarantee) has been provided with the @(':clause-processor')
 rule or @(tsee set-skip-meta-termp-checks) has been used with an active trust
 tag to skip the check at the user's risk.</p>

 <p>The proof also aborts when the clause-processor function returns at least
 two values and the first value returned &mdash; the ``@('erp')'' value from
 cases [3] and [3+] above &mdash; is not @('nil').  In that case, @('erp') is
 used for printing an error message as follows: if it is a string, then that
 string is printed; but if it is a non-empty true list whose first element is a
 string, then it is printed as though by @('(fmt ~@0 (list (cons #\0 erp))
 ...)') (see @(see fmt)).  Otherwise, a non-@('nil') @('erp') value causes a
 generic error message to be printed.</p>

 <p>If there is no error as above, but the @('CL-PROC') call returns a clause
 list whose single element is equal to the input clause, then the hint is
 ignored since we are left with the goal with which we started.  In that case,
 the other prover processes are then applied as usual (see @(see
 hints-and-the-waterfall)).</p>

 <p>You can see all current @(':clause-processor') rules by issuing the
 following command: @('(print-clause-processor-rules)').</p>

 <p>The following paper discusses ACL2 clause-processors at a high level
 suitable for a non-ACL2 audience:</p>

 <blockquote>

 <p>M. Kaufmann, J S. Moore, S. Ray, and E. Reeber, ``Integrating External
 Deduction Tools with ACL2.''  <i>Journal of Applied Logic</i> (Special Issue:
 Empirically Successful Computerized Reasoning), Volume 7, Issue 1, March 2009,
 pp. 3&ndash;25.  Also published online (DOI @('10.1016/j.jal.2007.07.002')).
 Preliminary version in: Proceedings of the 6th International Workshop on the
 Implementation of Logics (IWIL 2006) (C. Benzmueller, B. Fischer, and
 G. Sutcliffe, editors), <a href='http://ceur-ws.org/Vol-212/'>CEUR Workshop
 Proceedings Vol. 212</a>, Phnom Penh, Cambodia, pp. 7&ndash;26, November
 2006.</p></blockquote>

 ")

(defxdoc clear-memoize-statistics
  :parents (memoize)
  :short "Clears all profiling info displayed by @('(')@(tsee
  memoize-summary)@(')')"
  :long "<p>Logically, this function just returns @('nil').  It clears all
 profiling info displayed by @('(')@(tsee memoize-summary)@(')')</p>

 @(def clear-memoize-statistics)")

(defxdoc clear-memoize-table
  :parents (memoize)
  :short "Forget values remembered for the given function"
  :long "<p>This function returns its argument, @('fn'), unchanged.  The values
 memoized for @('fn') are forgotten.</p>

 @(def clear-memoize-table)")

(defxdoc clear-memoize-tables
  :parents (memoize)
  :short "Forget values remembered for all the memoized functions"
  :long "<p>@('Clear-memoize-tables') is a logical no-op.  All memoized values
 are forgotten.  It returns @('nil'), invoking @(tsee clear-memoize-table) for
 each memoized function.</p>

 @(def clear-memoize-tables)")

(defxdoc close-trace-file
  :parents (trace)
  :short "Stop redirecting trace output to a file"
  :long "@({
  General Form:
  (close-trace-file) ; trace output is no longer redirected to a file
 })

 <p>Output from @(tsee trace$) normally goes to the screen, or more precisely,
 @(tsee standard-co).  It can be redirected to a file; see @(see
 open-trace-file).  Use @('close-trace-file') to redirect trace output to
 @(tsee standard-co).</p>")

(defxdoc code-char
  :parents (characters numbers acl2-built-ins)
  :short "The character corresponding to a given numeric code"
  :long "<p>This function maps a numeric code to the corresponding character,
  for example: @('(code-char 65)') evaluates to @('#\A').  See @(tsee
  char-code) for a sort of inverse function, which maps a character to its
  code.</p>

 <p>Completion Axiom (@('completion-of-code-char')):</p>

 @({
  (equal (code-char x)
         (if (and (integerp x)
                  (>= x 0)
                  (< x 256))
             (code-char x)
           (code-char 0)))
 })

 <p>@(see Guard) for @('(code-char x)'):</p>

 @({
  (and (integerp x)
       (>= x 0)
       (< x 256))
 })

 <p>ACL2 supports 8-bit @(see characters).  Inputs not between @('0') and
 @('255') are treated as @('0').</p>")

(defxdoc coerce
  :parents (strings characters acl2-built-ins)
  :short "Coerce a character list to a string and a string to a list"
  :long "<p>Completion Axiom (@('completion-of-coerce')):</p>

 @({
  (equal (coerce x y)
         (cond
          ((equal y 'list)
           (if (stringp x)
               (coerce x 'list)
             nil))
          (t
           (coerce (make-character-list x) 'string))))
 })

 <p>@(see Guard) for @('(coerce x y)'):</p>

 @({
  (if (equal y 'list)
      (stringp x)
    (if (equal y 'string)
        (character-listp x)
      nil))
 })

 <p>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).</p>

 <h4>Logical Note</h4>

 <p>The function @('coerce') can be viewed as the constructor for strings.  As
 discussed in Section 7 of "<a
 href='http://www.cs.utexas.edu/users/moore/publications/km97a.pdf'>A Precise
 Description of the ACL2 Logic</a>" (Matt Kaufmann and J Moore, April, 1998),
 a string may be built by coercing its list of characters: for example,
 @('"abc"') is @('(coerce '(#\a #\b #\c) 'string)').  More precisely,
 @('"abc"') is an abbreviation for @('(coerce '(#\a #\b #\c) 'string)'),
 where even more pedantically, @(''(#\a #\b #\c)') is an abbreviation for
 @('(cons '#\a (cons '#\b (cons '#\c 'nil)))').</p>")

(defxdoc command
  :parents (history)
  :short "Forms you type at the top-level, but..."
  :long "<p>...the word ``command'' usually refers to a top-level form whose
 evaluation produces a new logical @(see world).</p>

 @({
  Typical commands are:
  (defun foo (x) (cons x x))
  (defthm consp-foo (consp (foo x)))
  (defrec pair (hd . tl) nil)
 })

 <p>The first two forms are examples of commands that are in fact primitive
 @(see events).  See @(see events).  @('Defrec'), on the other hand, is a macro
 that expands into a @(tsee progn) of several primitive @(see events).  In
 general, a @(see world) extending command generates one or more @(see
 events).</p>

 <p>Both @(see events) and commands leave landmarks on the @(see world) that
 enable us to determine how the given @(see world) was created from the
 previous one.  Most of your interactions will occur at the command level,
 i.e., you type commands, you print previous commands, and you undo back
 through commands.  Commands are denoted by command descriptors.  See @(see
 command-descriptor).</p>")

(defxdoc command-descriptor
  :parents (history)
  :short "An object describing a particular @(see command) typed by the user"
  :long "@({
  Examples:

  :max      ; the command most recently typed by the user
  :x        ; synonymous with :max
  (:x -1)   ; the command before the most recent one
  (:x -2)   ; the command before that
  :x-2      ; synonymous with (:x -2)
  5         ; the fifth command typed by the user
  1         ; the first command typed by the user
  0         ; the last command of the system initialization
  -1        ; the next-to-last initialization command
  :min      ; the first command of the initialization
  :start    ; the last command of the initial ACL2 logical world
  fn        ; the command that introduced the logical name fn
  (:search (defmacro foo-bar))
            ; the first command encountered in a search from :max to
            ; 0 that either contains defmacro and foo-bar in the
            ; command form or contains defmacro and foo-bar in some
            ; event within its block.
 })

 <p>The recorded @(see history) of your interactions with the top-level ACL2
 @(see command) loop is marked by the @(see command)s you typed that changed
 the logical @(see world).  Each such @(see command) generated one or more
 @(see events), since the only way for you to change the logical @(see world)
 is to execute an event function.  See @(see command) and see @(see events).
 We divide @(see history) into ``@(see command) blocks,'' grouping together
 each @(see world) changing @(see command) and its @(see events).  A ``@(see
 command) descriptor'' is an object that can be used to describe a particular
 @(see command) in the @(see history) of the ongoing session.</p>

 <p>Each @(see command) is assigned a unique integer called its ``@(see
 command) number'' which indicates the @(see command)'s position in the
 chronological ordering of all of the @(see command)s ever executed in this
 session (including those executed to initialize the system).  We assign the
 number 1 to the first @(see command) you type to ACL2.  We assign 2 to the
 second and so on.  The non-positive integers are assigned to ``prehistoric''
 @(see command)s, i.e., the @(see command)s used to initialize the ACL2 system:
 0 is the last @(see command) of the initialization, -1 is the one before that,
 etc.</p>

 <p>The legal @(see command) descriptors are described below.  We use @('n') to
 denote any integer, @('sym') to denote any logical name (see @(see
 logical-name)), and @('cd') to denote, recursively, any @(see command)
 descriptor.</p>

 @({
   command                   command
  descriptor                described

  :max   -- the most recently executed command (i.e., the one with
            the largest command number)
  :x     -- synonymous with :max
  :x-k   -- synonymous with (:x -k), if k is an integer and k>0
  :min   -- the earliest command (i.e., the one with the smallest
            command number and hence the first command of the system
            initialization)
  :start -- the last command when ACL2 starts up
  n      -- command number n  (If n is not in the
            range :min<=n<=:max, n is replaced by the nearest of :min
            and :max.)
  sym    -- the command that introduced the logical name sym
  (cd n) -- the command whose number is n plus the command number of
            the command described by cd
  (:search pat cd1 cd2)
            In this command descriptor, pat must be either an atom or
            a true list of atoms and cd1 and cd2 must be command
            descriptors.  We search the interval from cd1 through cd2
            for the first command that matches pat.  Note that if cd1
            occurs chronologically after cd2, the search is
            ``backwards'' through history while if cd1 occurs
            chronologically before cd2, the search is ``forwards''.  A
            backwards search will find the most recent match; a
            forward search will find the chronologically earliest
            match.  A command matches pat if either the command form
            itself or one of the events in the block contains pat (or
            all of the atoms in pat if pat is a list).
  (:search pat)
            the command found by (:search pat :max 0), i.e., the most
            recent command matching pat that was part of the user's
            session, not part of the system initialization.
 })")

(defxdoc command-line
  :parents (interfacing-tools)
  :short "Handling of command-line arguments when ACL2 is invoked"
  :long "<p>You may provide command-line arguments when invoking ACL2, which
 are passed to the host Lisp.  For more information on this topic, along with a
 discussion of how to save an ACL2 executable that avoids passing command-line
 arguments to the host Lisp, see @(see save-exec).</p>")

(defxdoc comment
  :parents (hide acl2-built-ins)
  :short "Variant of @(tsee prog2$) to help debug evaluation failures during
 proofs"
  :long "<p>Semantically, @('(comment x y)') equals @('y'); the value of @('x')
 is ignored.  Thus @('comment') is much like @(tsee prog2$).  However, when you
 see a call of @('comment') in ACL2 proof output, it will likely be under a
 call of @(tsee hide), with information that may be helpful in understanding
 why the call of @('hide') was inserted.  Below we illustrate the various ways
 in which ACL2 may replace a term @('tm') by @('(hide (comment "..."
 tm))').  (On occasion you will simply see @('(hide tm)'); such cases are not
 discussed here.)</p>

 <p>Also see @(see hide) for further discussion of how to avoid such proof
 failures, and for how to keep the prover from inserting a @('comment') call
 under a call of @(tsee hide).</p>

 <h3>Evaluation during rewriting</h3>

 <p>Forms:</p>

 @({
 (HIDE (COMMENT "Failed attempt to call constrained function <fn>" <term>))
 (HIDE (COMMENT "Failed attempt to call non-executable function <fn>" <term>))
 })

 <p>Consider the following example.</p>

 @({
 (defstub f (x) t)
 (defun g (x) (cons (f x) x))
 (defund h (x) (cons x (cdr (g x))))
 (thm (equal (h 3) '(3 . 3)))
 })

 <p>Note that the @(see definition) of @('h') is disabled, but its @(see
 executable-counterpart) is not.  The proof attempt fails for the @(tsee thm)
 call, indicating the checkpoint shown below.</p>

 @({
 *** Key checkpoint at the top level: ***

 Goal'
 (EQUAL
  (HIDE
    (COMMENT "Failed attempt to call constrained function F;
 see :DOC comment"
             (H 3)))
  '(3 . 3))
 })

 <p>The first argument of @('equal') is logically just @('(h 3)').  But the
 @('comment') and @('hide') wrappers are telling us that evaluation of @('(h
 3)') failed because it led to a call of the constrained function @('f').  It
 is easy to see why in this case, by looking at the definitions, where @('h')
 calls @('g'), which calls @('f').  But more complicated such failures may be
 difficult to understand without such information.  In very complicated cases,
 one might even want to use the Lisp debugger after designating a @(tsee
 break$) call using @(tsee trace$), like this (here, shown using host Lisp
 CCL).</p>

 @({
 ACL2 !>(trace$ (f :entry (break$)))
  ((F :ENTRY (BREAK$)))
 ACL2 !>(thm (equal (h 3) '(3 . 3)))

 > Break: Break
 > While executing: BREAK$, in process listener(1).
 > Type :GO to continue, :POP to abort, :R for a list of available restarts.
 > If continued: Return from BREAK.
 > Type :? for other options.
 1 > :b ; user input to get backtrace
  (262932A0) : 0 (BREAK$) 157
  (262932F0) : 1 (F 3) 141
  (26293338) : 2 (FUNCALL #'#<(:INTERNAL ACL2_*1*_ACL2::G ACL2_*1*_ACL2::G)> 3) 37
  (26293350) : 3 (FUNCALL #'#<(:INTERNAL ACL2_*1*_ACL2::H ACL2_*1*_ACL2::H)> 3) 37
  (26293368) : 4 (RAW-EV-FNCALL H (3) NIL NIL [[.. output elided ..]]
 })

 <p>This output from Lisp is quite low-level, but reading from the bottom up
 provides the following sequence of events.</p>

 <ul>

 <li>4. Call @('h') with argument list @('(3)').</li>

 <li>3. Call the @(see executable-counterpart) of @('h').</li>

 <li>2. Call the @(see executable-counterpart) of @('g').</li>

 <li>1. Attempt to call the constrained function, @('f').</li>

 </ul>

 <p>An easy way to avoid this proof failure is to avoid execution of calls of
 @('h') and @('g'), as follows.</p>

 @({
 (thm (equal (h 3) '(3 . 3))
      :hints (("Goal" :in-theory (disable (:e g) (:e h)))))
 })

 <p>(It actually suffices to disable only @('(:e h)'), but the workings of the
 ACL2 rewriter are out of scope here.)</p>

 <p>If the offending function (here, @('f')) is introduced as @(see
 non-executable) rather than constrained, in particular if that function is
 defined using @(tsee defun-nx) or @(tsee defund-nx), then in the first
 argument of comment you will see ``non-executable'' instead of
 ``constrained''.</p>

 <h3>Evaluation during substitution</h3>

 <p>Form:</p>

 @({
 (HIDE
  (COMMENT
   "Failed attempt (during substitution) to call constrained function <fn>;
 see :DOC comment"
   <term>))
 })

 <p>Consider how ACL2 approaches the proof of the non-theorem below.</p>

 @({
 (defstub foo (x) t)
 (defund bar (x) (foo x))
 (thm (implies (equal x 3) (equal (bar x) yyy)))
 })

 <p>The prover attacks the @(tsee thm) event by substituting the constant
 @(''3') for @('x'), which results in an attempt to evaluate @('(bar 3)').
 This evaluation fails because @('bar') calls the undefined function @('foo').
 The checkpoint is as follows.</p>

 @({
 (EQUAL
  (HIDE
   (COMMENT
      "Failed attempt (during substitution) to call constrained function FOO;
 see :DOC comment"
      (BAR 3)))
  YYY)
 })

 <h3>Failure to expand using a rule</h3>

 <p>Form:</p>

 @({
 (HIDE (COMMENT "Unable to expand using the rule <name>;
 see :DOC comment"
                <term>))
 })

 <p>Consider how ACL2 approaches the proof for the second event below.</p>

 @({
 (defthm nth-open (implies (and (consp x) (posp n))
                           (equal (nth n x) (nth (1- n) (cdr x))))
   :rule-classes ((:definition :controller-alist ((nth t t)) :install-body t)))
 (thm (equal (nth i y) zzz)
      :hints (("Goal" :expand (nth i y) :do-not-induct t)))
 })

 <p>The checkpoint is as follows.  What happened is that the rule @('nth-open')
 had a hypothesis that was false when an attempt was made to apply it to the
 term @('(nth i y)').</p>

 @({
 (IMPLIES
  (NOT (CONSP Y))
  (EQUAL
   (HIDE (COMMENT "Unable to expand using the rule NTH-OPEN;
 see :DOC comment"
                  (NTH I Y)))
   ZZZ))
 })

 <h3>Failure due to disabled or missing warrants</h3>

 <p>Forms:</p>

 @({
 (HIDE (COMMENT "Call failed because the rule apply$-<fn> is disabled;
 see :DOC comment"
       <term>))
 (HIDE (COMMENT "Call failed because the warrant for <fn> is not known to be true;
 see :DOC comment"
       <term>))
 })

 <p>The first of these forms may appear when an attempt to evaluate a call of
 @(tsee apply$) fails because a necessary @(see warrant) is disable)d.  The
 second form may appear when the warrant is not known to be true in the present
 context, either because it is known to be false or because it cannot be
 assumed true because forcing is @(see disable)d.  In the following example,
 the attempt to simplify the call of @('apply$') in the theorem ultimately
 leads to an attempt to evaluate a call of @(tsee ev$), which ultimately fails
 because it leads to a call to evaluate @('(apply$ 'bar '(3))') @('bar').  That
 call causes an error because the warrant is unavailable since the rule
 @('apply$-bar') is disabled, hence cannot rewrite a term @('(apply$ 'bar
 args)') to @('(bar (car args))').</p>

 @({
 (include-book "projects/apply/top" :dir :system)
 (defun$ bar (x) x)
 (thm (implies (warrant bar)
               (equal (apply$ '(lambda (y) (bar y)) '(3)) 3))
      :hints (("Goal" :in-theory (disable apply$-bar ev$))))
 })

 <p>The checkpoint in the proof for the @('thm') just above is as follows.</p>

 @({
 (IMPLIES
  (APPLY$-WARRANT-BAR)
  (EQUAL
   (HIDE
    (COMMENT
       "Call failed because the rule APPLY$-BAR is disabled;
 see :DOC comment"
       (EV$ '(BAR Y) '((Y . 3)))))
   3))
 })

 <p>Similarly, if we instead submit the following event, we see the other such
 message, in this case about a false warrant.</p>

 @({
 (thm (implies (not (warrant bar))
               (equal (apply$ '(lambda (y) (bar y)) '(3)) 3))
      :hints (("Goal" :in-theory (disable ev$))))
 })

 <p>Here is the resulting checkpoint.</p>

 @({
 (IMPLIES
  (NOT (APPLY$-WARRANT-BAR))
  (EQUAL
   (HIDE
    (COMMENT
     "Call failed because the warrant for BAR is not known to be true;
 see :DOC comment"
     (EV$ '(BAR Y) '((Y . 3)))))
   3))
 })

 <p>Our final example illustrates a failure due to forcing being disabled.  The
 use of @(tsee loop$) in the definition of @('bar') expands to create a call of
 @(tsee ev$), which cannot be simplified during the proof of the @(tsee thm)
 below because the necessary warrant hypothesis is missing and cannot be
 forced, since forcing is disabled (see also @(see disable-forcing)).</p>

 @({
 (defun$ hello (x)
    (declare (xargs :guard t))
    (list 'hi x))

 (defun bar (lst)
    (declare (xargs :guard (true-listp lst)))
    (loop$ for name in lst collect (hello name))))

 (thm (equal (bar '(john))
             '((hi john)))
      :hints (("Goal" :in-theory (disable (:e force)))))
 })

 <p>Here is the resulting checkpoint.</p>

 @({
 (EQUAL
  (HIDE
   (COMMENT
    "Call failed because the warrant for HELLO is not known to be true;
 see :DOC comment"
    (EV$ '(RETURN-LAST 'PROGN
                       '(LAMBDA$ (LOOP$-IVAR)
                          (LET ((NAME LOOP$-IVAR))
                            (DECLARE (IGNORABLE NAME))
                            (HELLO NAME)))
                       ((LAMBDA (NAME) (HELLO NAME))
                        LOOP$-IVAR))
         '((LOOP$-IVAR . JOHN)))))
  '(HI JOHN))
 })")

(defxdoc common-lisp
  :parents (about-acl2)
  :short "Relation to Common Lisp, including deviations from the spec"
  :long "<p>ACL2 is a logic, a theorem prover, and a programming language based
 on Common Lisp.  A connection with Common Lisp is established with guards (see
 @(see guard)).</p>

 <p>However, here we document potential deviations from Common Lisp semantics
 even in the presence of verified guards.  Our view is that these deviations
 are extremely unlikely to manifest; indeed, as of this writing we are unaware
 of any cases in which these issues arise in practice.  However, we feel
 obligated to acknowledge their possibility, which could result in surprises
 during evaluation or even proof.</p>

 <p>The Common Lisp spec allows certain predicates to return what it calls
 ``generalized Booleans,'' which are really arbitrary values that are to be
 viewed as either @('nil') or non-@('nil').  However, in ACL2 these functions
 are assumed to return @('nil') or @('t').  For details, see @(see
 generalized-booleans).</p>

 <p>The execution of forms with @(':')@(tsee program) mode functions can result
 in calls of functions on arguments that do not satisfy their @(see guard)s.
 In practice, this simply causes hard Lisp errors.  But in principle one could
 imagine a damaged Lisp image that operates incorrectly.  See @(see
 defun-mode-caveat).</p>

 <p>The Common Lisp spec, specifically
 Section @(`(:raw (clhs  "Body/03_bbc.htm" "Section 3.2.2.3"))`)
 of the @(`(:raw (clhs "Front" "Common Lisp Hyperspec"))`),
 allows for undefined results when a function is ``multiply defined'' in a
 compiled file.  ACL2 allows redundant @(tsee defun)s in a book, and in general
 @(see books) are compiled by @('certify-book') (but see @(see certify-book)
 and see @(see compilation) for how to control such compilation).  Moreover,
 ACL2 provides a redefinition capability (see @(see ld-redefinition-action) and
 see @(see redef)), and the above section also allows for undefined results
 when a function is defined in a compiled file and then redefined,
 presumably (for example) because of inlining.</p>")

(defxdoc community-books
  :parents (books)
  :short "Libraries of ACL2 @(see books) developed by the ACL2 community."
  :long "<p>This topic discusses ACL2 @(see books), which are files of ACL2
 @(see events) like definitions and theorems.  See also @(see community).</p>

 <p>The ACL2 <b>Community Books</b> are the canonical set of open-source books
 for ACL2, developed since the early 1990s by members of the ACL2 community.
 They include libraries for reasoning in many domains, macro libraries for more
 quickly writing and documenting code, interfacing tools for connecting ACL2 to
 other systems, productivity tools for better proof automation and debugging,
 and specialty libraries for areas like hardware verification.</p>

 <p>Most installations of ACL2 contain a copy of the Community Books.  See
 @(see installation).</p>

 <p>Users are encouraged to contribute their own books.  See
 @(see how-to-contribute).</p>

 <p>See @(see community) for more ways to become involved with the ACL2
 community.</p>")

(defxdoc comp
  :parents (compilation events acl2-built-ins)
  :short "Compile some ACL2 functions"
  :long "<p>NOTE: @('Comp') is a no-op if explicit compilation is suppressed;
 see @(see compilation).  The documentation here assumes that this is not the
 case.  See @(see evaluation) for background on executable-counterpart and
 submitted functions.</p>

 @({
  Examples:
  :comp t          ; compile all uncompiled ACL2 functions
  (comp t)         ; same as above, but can be put into a book
  (comp :exec)     ; compile all uncompiled executable-counterpart definitions
  :comp foo        ; compile the defined function foo (both its submitted and
                   ; executable-counterpart functions)
  :comp (:raw foo) ; compile the submitted function for the defined function foo
                   ; but not the corresponding executable-counterpart
  :comp (foo bar)  ; compile the defined functions foo and bar
  :comp (foo (:raw bar))  ; compile the defined functions foo and bar, but for
                          ; bar do not compile the executable-counterpart

  General Form:
  :comp specifier
  where specifier is one of the following:

    t                     compile all user-defined ACL2 functions that are
                            currently uncompiled (redefined built-in functions
                            are not recompiled)
    :exec                 same as t, except that only executable-counterparts
                            are compiled (see below), not submitted definitions
    :raw                  same as t, except that only submitted definitions are
                            compiled, not executable-counterparts
    (name-1 ... name-k)   a non-empty list of names of functions defined by
                            DEFUN in ACL2, except that each name-i can be of
                            the form (:raw sym) or (:exec sym), where sym is
                          the name of such a function
    name                  same as (name)
 })

 <p>When you define a function in ACL2, you are really causing two definitions
 to be made ``under the hood'' in Common Lisp: the definition is submitted
 explicitly to raw Lisp, but so is a corresponding executable-counterpart; see
 @(see evaluation).  If guards have not been verified, then only the
 executable-counterpart will be evaluated; see @(see evaluation) and see @(see
 guards-and-evaluation), in particular the section titled ``Guards and
 evaluation V: efficiency issues''.</p>

 <p>Thus, if you are not verifying @(see guard)s and you want the benefit of
 Lisp compilation for speed and space efficiency, then you may want to place
 the form @('(comp :exec)') in your @(see books).</p>

 <p>Generally it is not necessary to place the form @('(comp t)'), or the form
 @('(comp :raw)'), in a book, because @(tsee certify-book) compiles the raw
 Lisp definitions anyhow, by default.  But you may wish to put @('(comp t)') or
 @('(comp fn1 fn2 ... fnk)') in a book when such a form precedes expensive
 calls of functions, for example for proofs involving calls of functions on
 large constants, or to support computationally expensive macroexpansion.</p>

 <p>As suggested by the examples above, if a function specifier is of the form
 @('(:raw fn)'), then @('fn') will be compiled in raw Common Lisp but its
 corresponding executable-counterpart definition will not be compiled; and for
 @('(:exec fn)'), it's the other way around.</p>

 <p>The use of @(':comp') may create various files whose names start with
 ``@('TMP*')'', but it then deletes them.  If you want to save these files,
 evaluate @('(assign keep-tmp-files t)').</p>

 <p>Also see @(see set-compile-fns) for a way to compile each function as it is
 defined.  But note that @('set-compile-fns') is ignored during @(tsee
 include-book).</p>

 <p>Note that if functions are traced (see @(see trace$)), then @('comp') will
 first untrace the functions that are to be compiled, then will do the
 compile(s), and finally will re-trace the functions that it untraced (using
 their original trace specs).  In particular, if you have traced a function and
 then you compile it using @(':comp'), the resulting traced function will be
 compiled as well unless you specified @(':compile nil') in your trace spec;
 and after you untrace the function it will definitely run compiled.</p>

 <p>We conclude with a technical remark only for those who use trust tags to
 write raw Lisp code.  @(':Comp') generally creates files to compile unless it
 is given a single function to compile.  Those files contain the ACL2
 definitions of all functions to compile, omitting those in the lists obtained
 by evaluating the forms @('(@ logic-fns-with-raw-code)') and @('(@
 program-fns-with-raw-code)').  @(':Comp') skips compilation for functions that
 are already compiled, as is typically the case when you redefine functions in
 raw Lisp using @(see include-raw).  But if you define interpreted (as opposed
 to compiled) functions with raw Lisp code, say by using trust tags (see @(see
 defttag)) and @(tsee progn!), then you are advised to add all such symbols to
 one of the lists stored in the two @(see state) globals above: to
 @('logic-fns-with-raw-code') if the function symbol is in @(':')@(tsee logic)
 mode, else to @('program-fns-with-raw-code').  Then, instead of the
 corresponding ACL2 definition (without raw Lisp code) being written to a file,
 the function symbol will be passed directly to the Lisp @('compile') function.
 Note that the above two state globals are both untouchable, so you may need to
 deal with that before modifying them, for example as follows (also see @(see
 remove-untouchable)).</p>

 @({
  (defttag t)
  (progn!
   :state-global-bindings
   ((acl2::temp-touchable-vars t acl2::set-temp-touchable-vars))
   (f-put-global 'acl2::logic-fns-with-raw-code
                 (cons 'my-fn (@ acl2::logic-fns-with-raw-code))
                 state))
 })")

(defxdoc comp-gcl
  :parents (compilation acl2-built-ins)
  :short "Compile some ACL2 functions leaving .c and .h files"
  :long "<p>@('Comp-gcl') is for use by experts who want to examine the results
 of GCL compilation, and it may only be used with ACL2 implementations built on
 top of GCL.  It takes exactly the same arguments as @(tsee comp), and has the
 same basic functionality (see @(see comp)), but has two additional effects.
 First, files @('"TMP.lisp"') and @('"TMP1.lisp"') are always created, even
 when a single function is specified.  Second, @('comp-gcl') always leaves
 files @('"TMP.c"'), @('"TMP.h"'), @('"TMP1.c"'), and @('"TMP1.h"')
 when compilation is complete.</p>")

(defxdoc compare-objects
  :parents (debugging)
  :short "show differences between two ACL2 objects"
  :long "<p>In theorem prover output it can sometimes be difficult to
  see where two Lisp objects differ.  (Emacs' compare-windows can often help.)
  This function is an attempt to help while remaining entirely in ACL2.</p>

  @({
  General Form:
  (compare-objects x y)
  })

  <p>where @('x') and @('y') are two (almost) arbitrary objects but which must
  both be @('cons') trees for the comparison to be non-trivial.  The output
  (described below) might be confusing if either object contains keywords of
  the form @(':<|s...|>'), where the ellipsis is the decimal representation of a
  natural number.  For example, the output would be confusing if @('x') or
  @('y') contained @(':|<s1>|') because @('compare-objects') inserts tokens
  like that to mark differences.</p>

  <p>@('Compare-objects') walks through both objects to detect where
  corresponding substructures first differ.  It replaces differences by the
  keyword symbols @(':|<s1>|'), @(':|<s2>|'), @(':|<s3>|'), ..., which we call
  ``placeholders.''  It then assembles a ``legend'' that displays triplets of
  the form @('(si xi yi)') where @('si') is a placeholder marking a position in
  the common superstructure of both @('x') and @('y') and @('xi') and @('yi')
  are the substructures of @('x') and @('y'), respectively, at that position
  that differ.  @('Compare-objects') returns a list consisting of the ``common
  object'' showing the shared superstructure and the legend.</p>

  <p>For example,</p>

  @({
  ACL2 !>(compare-objects '(a b c) '(a b . c))
  ((:OBJ (A B . :|<s1>|))
   (:LEGEND ((:|<s1>| (C) C))))

  ACL2 !>(compare-objects '(f x y (g x '(a b c)))
                          '(f y x (g x '(a b c . d))))
  ((:OBJ (F :|<s1>|
            :|<s2>| (G X '(A B C . :|<s3>|))))
   (:LEGEND ((:|<s1>| X Y)
             (:|<s2>| Y X)
             (:|<s3>| NIL D))))
  })

  <p>By the way, the @('brr') command @(':')@(tsee explain-near-miss) sometimes
  calls @('compare-objects') to show the differences between two unequal quoted
  constants involved in a mismatch.  When @(':explain-near-miss') prettyprints
  the output of @('compare-object') it does so with an @(tsee evisc-tuple) that
  simplifies the placeholders.  @(':Explain-near-miss') would display the
  second example above as</p>

  @({
  ((:OBJ '(F <s1> <s2> (G X '(A B C . <s3>))))
   (:LEGEND ((<s1> X Y) (<s2> Y X) (<s3> NIL D)))).
  })

  <p>@('Compare-objects') might be especially helpful when looking at big
  @('lambda') objects as produced by translating and rewriting @(tsee loop$)
  expressions.  For example, below we use @('compare-objects') to discover
  where two large @('DO$') terms differ.</p>

  @({
  ACL2 !>(compare-objects
  '(DO$   ; First term
   '(LAMBDA (ALIST)
            (ACL2-COUNT (CDR (ASSOC-EQ-SAFE 'LST ALIST))))
   (CONS (CONS 'LST LST0) '((ANS . 0)))
   '(LAMBDA (ALIST)
            (IF (ENDP (CDR (ASSOC-EQ-SAFE 'LST ALIST)))
                (CONS ':RETURN
                      (CONS (CDR (ASSOC-EQ-SAFE 'ANS ALIST))
                            (CONS (CONS (CONS 'LST
                                              (CDR (ASSOC-EQ-SAFE 'LST ALIST)))
                                        (CONS (CONS 'ANS
                                                    (CDR (ASSOC-EQ-SAFE 'ANS ALIST)))
                                              'NIL))
                                  'NIL)))
                (CONS
                 'NIL
                 (CONS
                  'NIL
                  (CONS (CONS (CONS 'LST
                                    (CDR (CDR (ASSOC-EQ-SAFE 'LST ALIST))))
                              (CONS (CONS 'ANS
                                          (BINARY-+ '1
                                                    (CDR (ASSOC-EQ-SAFE 'ANS ALIST))))
                                    'NIL))
                        'NIL)))))
   '(LAMBDA (ALIST)
            (CONS 'NIL
                  (CONS 'NIL
                        (CONS (CONS (CONS 'LST
                                          (CDR (ASSOC-EQ-SAFE 'LST ALIST)))
                                    (CONS (CONS 'ANS
                                                (CDR (ASSOC-EQ-SAFE 'ANS ALIST)))
                                          'NIL))
                              'NIL))))
   '(NIL)
   'NIL)
  '(DO$   ; Second term
   '(LAMBDA (ALIST)
            (ACL2-COUNT (CDR (ASSOC-EQ-SAFE 'LST ALIST))))
   (CONS (CONS 'LST LST0) '((ANS . 0)))
   '(LAMBDA (ALIST)
            (IF (ENDP (CDR (ASSOC-EQ-SAFE 'LST ALIST)))
                (CONS ':RETURN
                      (CONS (CDR (ASSOC-EQ-SAFE 'ANS ALIST))
                            (CONS (CONS (CONS 'LST
                                              (CDR (ASSOC-EQ-SAFE 'LST ALIST)))
                                        (CONS (CONS 'ANS
                                                    (CDR (ASSOC-EQ-SAFE 'ANS ALIST)))
                                              'NIL))
                                  'NIL)))
                (CONS
                 'NIL
                 (CONS
                  'NIL
                  (CONS (CONS (CONS 'LST
                                    (CDR (CDR (ASSOC-EQ-SAFE 'LST ALIST))))
                              (CONS (CONS 'ANS
                                          (BINARY-+ '1
                                                    (CDR (ASSOC-EQ 'ANS ALIST))))
                                    'NIL))
                        'NIL)))))
   '(LAMBDA (ALIST)
            (CONS 'NIL
                  (CONS 'NIL
                        (CONS (CONS (CONS 'LST
                                          (CDR (ASSOC-EQ-SAFE 'LST ALIST)))
                                    (CONS (CONS 'ANS
                                                (CDR (ASSOC-EQ-SAFE 'ANS ALIST)))
                                          'NIL))
                              'NIL))))
   '(NIL)
   'NIL))
 ((:OBJ
  (DO$
   '(LAMBDA (ALIST)
      (ACL2-COUNT (CDR (ASSOC-EQ-SAFE 'LST ALIST))))
   (CONS (CONS 'LST LST0) '((ANS . 0)))
   '(LAMBDA (ALIST)
     (IF
       (ENDP (CDR (ASSOC-EQ-SAFE 'LST ALIST)))
       (CONS ':RETURN
             (CONS (CDR (ASSOC-EQ-SAFE 'ANS ALIST))
                   (CONS (CONS (CONS 'LST
                                     (CDR (ASSOC-EQ-SAFE 'LST ALIST)))
                               (CONS (CONS 'ANS
                                           (CDR (ASSOC-EQ-SAFE 'ANS ALIST)))
                                     'NIL))
                         'NIL)))
      (CONS
         'NIL
         (CONS 'NIL
               (CONS (CONS (CONS 'LST
                                 (CDR (CDR (ASSOC-EQ-SAFE 'LST ALIST))))
                           (CONS (CONS 'ANS
                                       (BINARY-+ '1
                                                 (CDR (:|<s1>| 'ANS ALIST))))
                                 'NIL))
                     'NIL)))))
   '(LAMBDA (ALIST)
      (CONS 'NIL
            (CONS 'NIL
                  (CONS (CONS (CONS 'LST
                                    (CDR (ASSOC-EQ-SAFE 'LST ALIST)))
                              (CONS (CONS 'ANS
                                          (CDR (ASSOC-EQ-SAFE 'ANS ALIST)))
                                    'NIL))
                        'NIL))))
   '(NIL)
   'NIL))
  (:LEGEND ((:|<s1>| ASSOC-EQ-SAFE ASSOC-EQ))))
  })

  <p>@('Compare-objects') tells us that a position @(':|<s1>|') the first term
  calls @('ASSOC-EQ-SAFE') while the second one calls @('ASSOC-EQ').</p>")

(defxdoc compilation
  :parents (programming)
  :short "Compiling ACL2 functions"
  :long "<p>ACL2 has several mechanisms to speed up the evaluation of function
 calls by <i>compiling</i> functions: see @(see comp), see @(see
 set-compile-fns), and see @(see certify-book).  The intention is that
 compilation never changes the value returned by a function call, though it
 could cause the call to succeed rather than fail, for example by avoiding a
 stack overflow.</p>

 <p>The @(tsee state) global variable @(''compiler-enabled') is set
 automatically when the system is built, and may depend on the underlying Lisp
 implementation.  (In order to disable the compiler at build time, which will
 defeat the speed-up but usually be pretty harmless when the host Lisp is CCL
 or SBCL, see the discussion of @('ACL2_COMPILER_DISABLED') in distributed file
 @('GNUmakefile').)  The value of @(''compiler-enabled'), as returned by @('(@
 compiler-enabled)'), can be @('t'), @(':books'), or @('nil').  If the value is
 @('nil'), then @(tsee include-book) and @(tsee certify-book) coerce their
 arguments @(':load-compile-file') and @('compile-flg') arguments
 (respectively) to @('nil').  Otherwise, the value is @(':books') or @('t') and
 there is no such coercion; but if the value is not @('t'), then @(tsee comp)
 and @(tsee set-compile-fns) are no-ops, which is probably desirable for Lisps
 such as CCL and SBCL that compile on-the-fly even when the compiler is not
 explicitly invoked.</p>

 <p>However, you may have reason to want to change the above (default)
 behavior.  To enable compilation by default for @(tsee certify-book) and
 @(tsee include-book) but not for @(tsee comp) or @(tsee set-compile-fns):</p>

 @({
  (set-compiler-enabled :books state)
 })

 <p>To enable compilation not only as above but also for @(tsee comp) and
 @(tsee set-compile-fns):</p>

 @({
  (set-compiler-enabled t state)
 })

 <p>To suppress compilation and loading of compiled files by @(tsee
 include-book) (for example, if you get a raw Lisp error such as ``Wrong FASL
 version''):</p>

 @({
  (set-compiler-enabled nil state)
 })

 <p>Remark for users of @(tsee make-event).  If @('set-compiler-enabled') is
 invoked during @('make-event') expansion, its effect on @(tsee state) global
 variable @(''compiler-enabled') will persist after evaluation completes for
 that @('make-event') form.  So for example, one might use the following idiom
 in a book so that for all books included on behalf of a given @(tsee
 include-book) form, no compiled files are loaded, but (optionally) no such
 effect takes place for later @('include-book') forms in that book.</p>

 @({
  (make-event
   (pprogn (f-put-global 'saved-compiler-enabled (@ compiler-enabled) state)
           (set-compiler-enabled nil state)
           (value '(value-triple nil)))
   :check-expansion t)
  (include-book "my-book")
  ; optional
  (make-event
   (pprogn (set-compiler-enabled (@ saved-compiler-enabled) state)
           (value '(value-triple nil)))
   :check-expansion t)
 })

 <p>Upon completion of an invocation of @(tsee include-book) or @(tsee
 certify-book), the value of @(tsee state) global variable
 @(''compiler-enabled') is restored to the value it had immediately before that
 invocation.</p>

 <p>See @(see book-compiled-file) for more discussion about compilation and
 @(see books).</p>

 <p>We close with a discussion of a feature that allows control over the
 loading of @('.port') files in close analogy to how loading of compiled files
 is controlled by @('set-compiler-enabled'), as described above.
 (See @(see uncertified-books) for a discussion of @('.port') files.)  A @(see
 state) global variable, @(''port-file-enabled') exists for this purpose, and
 it is set as follows.</p>

 @({
  (set-port-file-enabled t state)   ; permit loading of .port files (default)
  (set-port-file-enabled nil state) ; skip loading of .port files
 })

 <p>Just as described above for state global @('compiler-enabled'), the value
 of @(''port-file-enabled') persists after @(tsee make-event) expansion and is
 restored after @(tsee certify-book) and @(tsee include-book).  The idiom
 displayed above, for avoiding loading of compiled files, can be modified or
 extended in the obvious way to avoid loading of @('.port') files.</p>")

(defxdoc compiling-acl2p
  :parents (parallelism)
  :short "Compiling ACL2(p)"
  :long "<p>This @(see documentation) topic relates to the experimental
 extension of ACL2 supporting parallel execution and proof; see @(see
 parallelism).  See @(see parallelism-tutorial) for an introduction to parallel
 programming in ACL2.</p>

 <p>You can build an experimental version of ACL2 that supports parallel
 execution in the following host Common Lisp implementations:</p>

 <blockquote><p>* CCL (OpenMCL)</p>

 <p>* Lispworks 6.0</p>

 <p>* SBCL with threads (feature @(':sb-thread'))</p></blockquote>

 <p>The command below will compile ACL2 to support parallel execution,
 including parallel execution during proofs.  Any non-empty string may be used
 in place of @('t'), and the value of @('LISP') (shown here as @('ccl')) is any
 Lisp executable on which one can build ACL2(p) (see @(see parallelism)).</p>

 @({
  make ACL2_PAR=t LISP=ccl
 })

 <p>So for example, to make an executable image and also documentation (which
 will appear in subdirectories @('doc/EMACS') and @('doc/HTML')), using the
 Lisp executable @('ccl'):</p>

 @({
  make large DOC ACL2_PAR=t LISP=ccl
 })")

(defxdoc complex
  :parents (numbers acl2-built-ins)
  :short "Create an ACL2 number"
  :long "@({
  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
 })

 <p>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 @(tsee
 complex-rationalp) is a recognizer for complex rational numbers, i.e. for ACL2
 numbers that are not rational numbers.</p>

 <p>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)').</p>

 <p>The functions @(tsee realpart) and @(tsee 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').</p>

 <p>The following built-in axiom may be useful for reasoning about complex
 numbers.</p>

 @({
  (defaxiom complex-definition
    (implies (and (real/rationalp x)
                  (real/rationalp y))
             (equal (complex x y)
                    (+ x (* #c(0 1) y))))
    :rule-classes nil)
 })

 <p>A completion axiom that shows what @('complex') returns on arguments
 violating its @(see guard) (which says that both arguments are rational
 numbers) is the following, named @('completion-of-complex').</p>

 @({
  (equal (complex x y)
         (complex (if (rationalp x) x 0)
                  (if (rationalp y) y 0)))
 })")

(defxdoc complex-rationalp
  :parents (numbers acl2-built-ins)
  :short "Recognizes complex rational numbers"
  :long "@({
  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
 })

 <p>See @(see complex) for more about complex rationals in ACL2.</p>")

(defxdoc complex/complex-rationalp
  :parents (numbers acl2-built-ins)
  :short "Recognizer for complex numbers"
  :long "<p>For most ACL2 users, this is a macro abbreviating
 @('complex-rationalp'); see @(see complex-rationalp).  In ACL2(r) (see @(see
 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 @(tsee
 complex-rationalp) instead.  Some community books use
 @('complex/complex-rationalp') so that they are suitable for ACL2(r) as
 well.</p>")

(defxdoc compound-recognizer
  :parents (rule-classes)
  :short "Make a rule used by the typing mechanism"
  :long "<p>See @(see rule-classes) for a general discussion of rule classes,
 including how they are used to build rules from formulas and a discussion of
 the various keywords in a rule class description.</p>

 @({
  Examples:
  (defthm alistp-implies-true-listp-compound-recognizer
    (implies (alistp x)                 ; When (alistp x) is assumed true, add
             (true-listp x))            ; the additional hypothesis that x is
    :rule-classes :compound-recognizer) ; of primitive type true-listp.

  (defthm natp-compound-recognizer      ; See discussion below.
    (equal (natp x)
           (and (integerp x)
                (<= 0 x)))
    :rule-classes :compound-recognizer)
 })

 <p>Before presenting the General Forms, we start with a motivating example:
 the second @(tsee defthm) form above, which provides a nice example of a
 @(':compound-recognizer') rule that is built into ACL2.  To see how this rule
 might be useful, consider the following (admittedly very simple) @(see
 events).</p>

 @({
  (defun triple (x)
    (* 3 x))

  (defthm triple-preserves-integerp
    (implies (integerp x)
             (integerp (triple x))))

  (in-theory (disable triple natp))
 })

 <p>If the above @(':compound-recognizer') rule is disabled, then the following
 trivial theorem fails as shown; we explain below.</p>

 @({
  (thm (implies (natp x)
                (integerp (triple x)))
    :hints (("Goal" :in-theory (disable natp-compound-recognizer))))
 })

 <p>The problem is that when ACL2 tries to rewrite the term @('(integerp
 (triple x))') using the @(':')@(tsee rewrite) rule
 @('triple-preserves-integerp'), it needs to rewrite the hypothesis
 @('(integerp x)') to @('t'), but instead what is known is @('(natp x)').  If
 we remove the hint, then the proof succeeds because the above
 @(':compound-recognizer') rule tells ACL2 that when assuming @('(natp x)') to
 be true, it should actually assume both @('(integerp x)') and @('(<= 0 x)') to
 be true.</p>

 @({
  General Forms:
  (implies (fn x) concl)               ; (1)
  (implies (not (fn x)) concl)         ; (2)
  (and (implies (fn x) concl1)         ; (3)
       (implies (not (fn x)) concl2))
  (if (fn x) concl1 concl2)            ; (4)
  (iff (fn x) concl)                   ; (5)
  (equal (fn x) concl)                 ; (6)
 })

 <p>where @('fn') is a Boolean valued function of one argument, @('x') is a
 variable symbol, and the system can deduce some restriction on the primitive
 type of @('x') from the assumption that @('concl') holds.  The last
 restriction is vague but one way to understand it is to strengthen it a little
 to ``and @('concl') is a non-tautological disjunction of the primitive type
 recognizers listed below.''</p>

 <p>The primitive ACL2 types and a suitable primitive recognizing expression
 for each are listed below.</p>

 @({
    type                suitable primitive recognizer

    zero                    (equal x 0)
    one                     (equal x 1)
    negative integers       (and (integerp x) (< x 0))
    positive integers > 1   (and (integerp x) (> x 1))
    negative ratio          (and (rationalp x)
                                 (not (integerp x))
                                 (< x 0))
    positive ratio          (and (rationalp x)
                                 (not (integerp x))
                                 (> x 0))
    complex rational        (complex-rationalp x)
    nil                     (equal x nil)
    t                       (equal x t)
    other symbols           (and (symbolp x)
                                 (not (equal x nil))
                                 (not (equal x t)))
    proper conses           (and (consp x)
                                 (true-listp x))
    improper conses         (and (consp x)
                                 (not (true-listp x)))
    strings                 (stringp x)
    characters              (characterp x)
 })

 <p>Thus, since the naturals comprise the types @('zero'), @('one'), and
 @('positive integers > 1'), a suitable @('concl') to recognize the naturals
 would be</p>

 @({
    (or (equal x 0)
        (equal x 1)
        (and (integerp x) (> x 1)))
 })

 <p>However, it turns out that we also permit @('(and (integerp x) (>= x 0))'),
 i.e. @('concl') doesn't literally need to be formed as a direct disjunction of
 terms from the table above.</p>

 <p>Similarly, the true-lists could be specified by</p>

 @({
    (or (equal x nil)
        (and (consp x)
             (true-listp x)))
 })

 <p>but we in fact allow @('(true-listp x)') as well.  When time permits we
 may document more fully what is allowed or implement a macro that permits
 direct specification of the desired type in terms of the primitives.</p>

 <p>There are essentially four forms of @(':compound-recognizer') rules, as the
 forms labeled (3) and (4) above are equivalent, as are those labeled (5) and
 (6).  We explain how such rules are used by considering the individual
 forms.</p>

 <p>Consider form (1), @('(implies (fn x) concl)').  The effect of such a rule
 is that when the rewriter assumes @('(fn x)') true, as it would while diving
 through @('(if (fn x) xxx ...)') to rewrite @('xxx'), it restricts the type of
 @('x') as specified by @('concl').  For example, if @('concl') is the term
 @('(integerp x)'), then when rewriting @('xxx'), @('x') will be assumed to be
 an integer.  However, when assuming @('(fn x)') false, as necessary in @('(if
 (fn x) ... xxx)'), the rule permits no additional assumptions about the type
 of @('x').  For example, if @('fn') is @('primep'), i.e., the predicate that
 recognizes prime numbers, then @('(implies (primep x) (and (integerp x) (>= x
 0)))') is a compound recognizer rule of the first form.  When @('(primep x)')
 is assumed true, the rewriter gains the additional information that @('x') is
 a natural number.  When @('(primep x)') is assumed false, no additional
 information is gained &mdash; since @('x') may be a non-prime natural or may
 not even be a natural.</p>

 <p>Form (2) is the symmetric case, when assuming @('(fn x)') false permits
 type restrictions on @('x') but assuming @('(fn x)') true permits no such
 restrictions.  For example, if we defined @('exprp') to be the recognizer for
 well-formed expressions for some language in which all symbols, numbers,
 character objects and strings were well-formed &mdash; e.g., the
 well-formedness rules only put restrictions on expressions represented by
 @(tsee consp)s &mdash; then the theorem @('(implies (not (exprp x)) (consp
 x))') is a rule of the second form.  Assuming @('(exprp x)') true tells us
 nothing about the type of @('x'); assuming it false tells us @('x') is a
 @(tsee consp).</p>

 <p>Forms (3) and (4), which are really equivalent, address themselves to the
 case where one type may be deduced from @('(fn x)') and a generally unrelated
 type may be deduced from its negation.  If we modified the expression
 recognizer above so that character objects are illegal, then rules of the
 forms (3) and (4) are</p>

 @({
  (and (implies (exprp x) (not (characterp x)))
       (implies (not (exprp x)) (or (consp x) (characterp x)))).
  (if (exprp x)
      (not (characterp x))
    (or (consp x) (characterp x)))
 })

 <p>Finally, rules of forms (5) and (6) address the case where @('fn')
 recognizes all and only the objects whose type is described.  In these cases,
 @('fn') is really just a new name for some ``compound recognizers.''  The
 classic example is @('(booleanp x)'), which is just a handy combination of two
 primitive types:</p>

 @({
  (iff (booleanp x) (or (equal x t) (equal x nil))).
 })

 <p>Often it is best to disable @('fn') after proving that it is a compound
 recognizer, since otherwise the term @('(fn x)') will be expanded and thus
 disappear.</p>

 <p>Every time you prove a new compound recognizer rule about @('fn') it
 overrides all previously proved compound recognizer rules about @('fn').
 Thus, if you want to establish the type implied by @('(fn x)') and you want to
 establish the type implied by @('(not (fn x))'), you must prove a compound
 recognizer rule of the third, fourth, fifth, or sixth forms.  Proving a rule
 of the first form followed by one of the second only leaves the second fact in
 the database.</p>

 <p>Compound recognizer rules can be disabled with the effect that older rules
 about @('fn'), if any, are exposed.</p>

 <p>If you prove more than one compound recognizer rule for a function, you may
 see a <b>warning</b> message to the effect that the new rule is not as
 ``restrictive'' as the old.  That is, the new rules do not give the rewriter
 strictly more type information than it already had.  The new rule is stored
 anyway, overriding the old, if enabled.  You may be playing subtle games with
 enabling or rewriting.  But two other interpretations are more likely, we
 think.  One is that you have forgotten about an earlier rule and should merely
 print it out to make sure it says what you intend, and then discard your new
 rule.  The other is that you meant to give the system more information and the
 system has simply been unable to extract the intended type information from
 the term you placed in the conclusion of the new rule.  Given our lack of
 specificity in saying how type information is extracted from rules, you can
 hardly blame yourself for this problem.  Sorry.  If you suspect you've been
 burned this way, you should rephrase the new rule in terms of the primitive
 recognizing expressions above and see if the warning is still given.  It would
 also be helpful to let us see your example so we can consider it as we
 redesign this stuff.</p>

 <p>Compound recognizer rules are similar to @(':')@(tsee forward-chaining)
 rules in that the system deduces new information from the act of assuming
 something true or false.  If a compound recognizer rule were stored as a
 forward chaining rule it would have essentially the same effect as described,
 when it has any effect at all.  The important point is that @(':')@(tsee
 forward-chaining) rules, because of their more general and expensive form, are
 used ``at the top level'' of the simplification process: we forward chain from
 assumptions in the goal being proved.  But compound recognizer rules are built
 in at the bottom-most level of the simplifier, where <see topic='@(url
 type-reasoning)'>type reasoning</see> is done.</p>

 <p>All that said, compound recognizer rules are a rather fancy, specialized
 mechanism.  It may be more appropriate to create @(':')@(tsee
 forward-chaining) rules instead of @(':compound-recognizer') rules.</p>")

(defxdoc compress1
  :parents (arrays acl2-built-ins)
  :short "Remove irrelevant pairs from a 1-dimensional array"
  :long "@({
  Example Form:
  (compress1 'delta1 a)

  General Form:
  (compress1 name alist)
 })

 <p>where @('name') is a symbol and @('alist') is a 1-dimensional array,
 generally named @('name').  See @(see arrays) for details.  Logically
 speaking, this function can remove irrelevant pairs from @('alist'), possibly
 shortening it.  The function returns a new array, @('alist''), with the same
 @(tsee header) (including name and dimension) as @('alist'), that, under
 @(tsee aref1), is everywhere equal to @('alist').  That is, @('(aref1 name
 alist' i)') is @('(aref1 name alist i)'), for all legal indices @('i').
 @('Alist'') may be shorter than @('alist') and the non-irrelevant pairs may
 occur in a different order than in @('alist').</p>

 <p>Practically speaking, this function plays an important role in the
 efficient implementation of @(tsee aref1).  In addition to creating the new
 array, @('alist''), @('compress1') makes that array the ``semantic value'' of
 @('name') and allocates a raw lisp array to @('name').  For each legal index,
 @('i'), that raw lisp array contains @('(aref1 name alist' i)') in slot
 @('i').  Thus, subsequent @(tsee aref1) operations can be executed in
 virtually constant time provided they are given @('name') and the @('alist'')
 returned by the most recently executed @('compress1') or @(tsee aset1) on
 @('name').  See @(see arrays).</p>

 <p>In general, @('compress1') returns an alist whose @(tsee cdr) is an
 association list whose keys are nonnegative integers in ascending order.
 However, if the @(tsee header) specifies an @(':order') of @('>') then the
 keys will occur in descending order; and if the @(':order') is @(':none') or
 @('nil') then the keys will not be sorted and the header may appear anywhere
 (even more than once), i.e., @('compress1') is logically the identity
 function (though it still attaches an array under the hood).  Note however
 that a @(tsee compress1) call is replaced by a hard error if the header
 specifies an @(':order') of @(':none') or @('nil') and the array's length
 exceeds the @(tsee maximum-length) field of its @(tsee header).</p>

 <p>We close with a remark concerning efficiency in the case that the
 @(':ORDER') specified by the given @(see array)'s @(see header) is @('<') or
 @('>') and the alist is properly ordered: header occurring only first, then
 ascending (for @(':ORDER <')) or descending (for @(':ORDER >')) order of
 indices, with no value in the alist equal to the @(':DEFAULT') specified by
 the header.  In particular, this can cut the time to run @('compress1') on an
 alist containing only the header by more than half.</p>

 @(def compress1)")

(defxdoc compress2
  :parents (arrays acl2-built-ins)
  :short "Remove irrelevant pairs from a 2-dimensional array"
  :long "@({
  Example Form:
  (compress2 'delta1 a)

  General Form:
  (compress2 name alist)
 })

 <p>where @('name') is a symbol and @('alist') is a 2-dimensional array,
 generally named @('name').  See @(see arrays) for details.  Logically
 speaking, this function removes irrelevant pairs from @('alist'), possibly
 shortening it.  The function returns a new array, @('alist''), with the same
 @(tsee header) (including name and dimension) as @('alist'), that, under
 @(tsee aref2), is everywhere equal to @('alist').  That is, @('(aref2 name
 alist' i j)') is @('(aref2 name alist i j)'), for all legal indices @('i') and
 @('j').  @('Alist'') may be shorter than @('alist') and the non-irrelevant
 pairs may occur in a different order in @('alist'') than in @('alist').</p>

 <p>Practically speaking, this function plays an important role in the
 efficient implementation of @(tsee aref2).  In addition to creating the new
 array, @('alist''), @('compress2') makes that array the ``semantic value'' of
 @('name') and allocates a raw lisp array to @('name').  For all legal indices,
 @('i') and @('j'), that raw lisp array contains @('(aref2 name alist' i j)')
 in slot @('i'),@('j').  Thus, subsequent @(tsee aref2) operations can be
 executed in virtually constant time provided they are given @('name') and the
 @('alist'') returned by the most recently executed @('compress2') or @(tsee
 aset2) on @('name').  See @(see arrays).</p>

 @(def compress2)")

(defxdoc computed-hints
  :parents (hints)
  :short "Computing advice to the theorem proving process"
  :long "@({
  General Form of :hints:
  (hint1 hint2 ... hintk)
 })

 <p>Each element, hinti, must be either a common hint or a computed hint.</p>

 <p>A common hint is of the form</p>

 @({
  (goal-spec :key1 val1 ... :keyn valn)
 })

 <p>where @('goal-spec') is as specified in @(see goal-spec) and each
 @(':keyi') and @('vali') is as specified in @(see hints).  Among the ``common
 hints'' we include both the primitive hints and user-defined custom keyword
 hints (see @(see custom-keyword-hints)).</p>

 <p>A computed hint may be a symbol, in which case it must be a function symbol
 of three, four or seven arguments.  Otherwise, a computed hint is a term with
 the following properties:</p>

 <p>(a) the only free variables allowed in the term are @('ID'), @('CLAUSE'),
 @('WORLD'), @('STABLE-UNDER-SIMPLIFICATIONP'), @('HIST'), @('PSPV'), @('CTX'),
 and @(tsee STATE);</p>

 <p>(b) the output signature of the term is either @('(MV * * STATE)'), which
 is to be treated as an error triple (see below), or is @('*'), denoting a
 single non-@(see stobj) value; and</p>

 <p>(c) in the former case of (b) above, the term is single-threaded in @(tsee
 STATE).</p>

 <p>If a computed hint is a function symbol @('fn'), whose arity n is therefore
 three, four, or seven, then it is treated as the term resulting from applying
 that @('fn') to the first n variables shown in (a) above.  Notice that it must
 then return a single non-@(see stobj) value, not an error triple, since
 @('state') is not one of the first seven variables shown in (a).</p>

 <p>Note: Error triples are an ACL2 idiom for implementing ``errors''; see
 @(see error-triple).  If a computation returns @('(mv erp val state)') in a
 context in which ACL2 is respecting the error triple convention (see @(see
 ld-error-triples) and see @(see ld-error-action)), then an error is deemed to
 have occurred if @('erp') is non-@('nil').  The computation is expected to
 have printed an appropriate error message to @(tsee state) and further
 computation is aborted.  On the other hand, if a computation returns an error
 triple in which @('erp') is nil, then ``value'' of the computation is taken to
 be the second component, @('val'), of the triple (along with the possibly
 modified @(tsee state)), and computation continues.  For more information
 about programming with error triples, see @(see programming-with-state).</p>

 <p>The function symbol cases are treated as abbreviations of the term @('(fn
 ID CLAUSE WORLD)'), @('(fn ID CLAUSE WORLD STABLE-UNDER-SIMPLIFICATIONP)'), or
 @('(fn ID CLAUSE WORLD STABLE-UNDER-SIMPLIFICATIONP HIST PSPV CTX)') as
 appropriate for the arity of @('fn').  (Note that this tells you which
 argument of @('fn') is which.)  Moreover, in these cases the value returned
 must be a single ordinary (non-@(see stobj)) value, not an error triple.  In
 the discussion below we assume all computed hints are of the term form.
 Indeed, we almost assume all computed hints are of the 3 and 4 argument forms.
 We only comment briefly on the 7 argument form in @(see
 using-computed-hints-8).</p>

 <p>The semantics of a computed hint term is as follows.  On every subgoal, the
 term is evaluated in an environment in which the variables mentioned in (a)
 above are bound to context-sensitive values explained below.  Either the
 computed hint signals an error, in which the proof attempt aborts, or else it
 returns a value, @('val') and a new state, @(tsee state).  Any changes to
 those parts of @(tsee state) that affect logical soundness are undone; more
 specifically, the values of symbols (sometimes called ``state global
 variables'') in the list @('*protected-system-state-globals*') in the global
 table of the state (see @(see state)) are restored when changed during
 evaluation.  The value, @('val'), of a non-erroneous computed hint calculation
 is either @('nil'), which means the computed hint did not apply to the subgoal
 in question, or it is an alternating list of @(':keyi vali') pairs as
 specified in @(see hints).  With one exception, those new hints are applied to
 the given subgoal as though the user had typed them explicitly.</p>

 <p>The exception is that the first keyword in the returned @('val') is allowed
 to be @(':COMPUTED-HINT-REPLACEMENT').  Its value should be @('nil'), @('t'),
 or a list of terms.  If this keyword is not present, the default value of
 @('nil') is provided.  We explain @(':COMPUTED-HINT-REPLACEMENT') below.</p>

 <p>The evaluation of a hint term is done with guard checking turned off (see
 @(see set-guard-checking)); e.g., the form @('(car 23)') in a computed hint
 returns @('nil') as per the axioms.</p>

 <p>When a non-@('nil') value is returned, the keyword/value pairs (other than
 the optional @(':COMPUTED-HINT-REPLACEMENT')) are used as the hint for the
 subgoal in question.  Thus, your job as the programmer of computed hints is
 either to cause an error, typically by invoking @(tsee er), or to return a
 non-erroneous value triple whose value is the list of keys and values you
 would have typed had you supplied a common hint for the subgoal. (In
 particular, any theory expressions in it are evaluated with respect to the
 global current-theory, not whatever theory is active at the subgoal in
 question.)  If the generated list of keywords and values is illegal, an error
 will be signaled and the proof attempt will be aborted.</p>

 <p>The purpose of the @(':COMPUTED-HINT-REPLACEMENT') keyword and its value,
 @('chr'), is to change the list of hints.  If @('chr') is @('nil'), then the
 computed hint which was applied is removed from the list of hints that is
 passed down to the children of the subgoal in question.  This is the default.
 If @('chr') is @('t'), then the computed hint is left in the list of hints.
 This means that the same computed hint may act on the children of the subgoal.
 Otherwise, @('chr') must be a list of terms, each of which is treated as a
 computed hint.  The computed hint which was applied is deleted from the list
 of hints and the computed hints in @('chr') are added to the list of hints
 passed to the children of the subgoal.  The ability to generate new computed
 hints and pass them down allows strange and wonderful behavior.  Notice that
 certain hints, for example @(':in-theory') and @(':expand') hints, which
 appear in the computed hint will continue to take effect even when @('chr') is
 @('nil').  This might give one the false impression that a removed computed
 hint still hangs around.  See @(see hints-and-the-waterfall) for a more
 detailed discussion about how @(':in-theory') and other hints are handled in
 the waterfall.</p>

 <p>For these purposes, the goals produced by induction and the top-level goals
 of forcing rounds are not considered children; all original hints are
 available to them.</p>

 <p>Only the first hint applicable to a goal, as specified in the user-supplied
 list of @(':hints') followed by the @(tsee default-hints-table), will be
 applied to that goal.  (For an advanced exception, see @(see
 override-hints).)</p>

 <p>It remains only to describe the bindings of the free variables.</p>

 <p>Suppose the theorem prover is working on a @(see clause) named by some
 @(tsee goal-spec), e.g., "Subgoal *1/2'''".  Corresponding to the printed
 @('goal-spec') is an internal data structure called a ``clause identifier''
 id.  See @(see clause-identifier).</p>

 <p>In the case of a common hint, the hint applies if the goal-spec of the hint
 is the same as the goal-spec of the clause in question.</p>

 <p>In the case of a computed hint, the variable @('ID') is bound to the clause
 id, the variable @('CLAUSE') is bound to the (translated form of the) clause,
 and the variable @('WORLD') is bound to the current ACL2 world.  The variable
 @('STABLE-UNDER-SIMPLIFICATIONP') is bound to @('t') or @('nil').  It is bound
 to @('t') only if the clause is known to be stable under simplification.  That
 is, the simplifier has been applied to the clause and did not change it.  Such
 a clause is sometimes known as a ``simplification checkpoint.''  It is
 frequently useful to inject hints (e.g., to enable a rule or provide a
 @(':use') hint) only when the goal in question has stabilized.  If a hint is
 provided, the processing of the clause starts over with simplification.</p>

 <p>As for @('CTX') and @(tsee STATE), they are provided so that you can pass
 them to the @(tsee er) macro to print error messages.</p>

 <p>The remaining variables, @('HIST') and @('PSPV') are not documented yet.
 Only users familiar with the internals of ACL2 are likely to need them or
 understand their values.</p>

 <p>For some instruction about how to use computed hints, see @(see
 using-computed-hints).</p>")

(defxdoc concatenate
  :parents (lists strings acl2-built-ins)
  :short "Concatenate lists or strings together"
  :long "@({
  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)
 })

 <p>where @('n >= 0') and either: @('result-type') is @(''')@(tsee string) and
 each @('xi') is a string; or @('result-type') is @(''')@(tsee list) and each
 @('xi') is a true list.  @('Concatenate') simply concatenates its arguments to
 form the result string or list.  Also see @(see append) and see @(see
 string-append).  (The latter immediately generates a call to @('concatenate')
 when applied to strings.)</p>

 <p>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.</p>

 <p>@('Concatenate') is a Common Lisp function.  See any Common Lisp
 documentation for more information.</p>

 @(def concatenate)")

(defxdoc cond
  :parents (basics acl2-built-ins)
  :short "Conditional based on if-then-else"
  :long "<p>@('Cond') is the construct for IF, THEN, ELSE IF, ...  The test is
 against @('nil').  The argument list for @('cond') is a list of ``cond
 clauses'', each of which is a list.  In ACL2, cond clauses must have length 1
 or 2.</p>

 @({
 ; Example 1.  The form
   (COND ((CONSP X) (FOO X Y))
         ((SYMBOLP X) (BAR X Y))
         (T (LIST X Y)))
 ; abbreviates the following.
   (IF (CONSP X)
       (FOO X Y)
       (IF (SYMBOLP X)
           (BAR X Y)
           (LIST X Y)))

 ; Example 2.  The form
   (COND ((CONSP X))
         ((SYMBOLP X) (BAR X Y)))
 ; abbreviates the following.
   (OR (CONSP X)
       (IF (SYMBOLP X) (BAR X Y) NIL))
 })

 <p>The results above were obtained by typing @(':trans1') followed by the form
 in the ACL2 loop, and then hitting @('<RETURN>').  See @(see trans1).  You can
 experiment in this way to see other such examples.</p>

 <p>@('Cond') is a Common Lisp macro.  See any Common Lisp documentation for
 more information.</p>

 @(def cond)
 @(def cond-macro)")

(defxdoc congruence
  :parents (rule-classes)
  :short "The relations to maintain while simplifying arguments"
  :long "<p>See @(see rule-classes) for a general discussion of rule classes
 and how they are used to build rules from formulas.  An example @(':')@(tsee
 corollary) formula from which a rule of class @(':congruence') might be built,
 assuming that @('set-equal') is a known @(see equivalence) relation, is:</p>

 @({
  Example:
  (defthm set-equal-implies-iff-memb-2
    (implies (set-equal x y)
             (iff (memb e x) (memb e y)))
    :rule-classes :congruence)
 })

 <p>Also see @(see defcong) and see @(see equivalence).</p>

 <p>NOTE: This topic discusses so-called ``classic'' congruence rules.  A more
 general class of rules, so-called ``patterned'' congruence rules, is
 supported.  We discuss only classic congruence rules below; for a discussion
 of patterned congruence rules, first read the present topic and then see @(see
 patterned-congruence).</p>

 @({
  General Form:
  (implies (equiv1 xk xk-equiv)
           (equiv2 (fn x1... xk       ...xn)
                   (fn x1... xk-equiv ...xn)))
 })

 <p>where @('equiv1') and @('equiv2') are known equivalence relations, @('fn')
 is an @('n-ary') function symbol other than @('if'), and the @('xi') and
 @('xk-equiv') are all distinct variables.  The effect of such a rule is to
 record that the @('equiv2')-equivalence of @('fn')-expressions can be
 maintained if, while rewriting the @('kth') argument position,
 @('equiv1')-equivalence is maintained.  See @(see equivalence) for a general
 discussion of the issues.  We say that @('equiv2'), above, is the ``outside
 equivalence'' in the rule and @('equiv1') is the ``inside equivalence for the
 @('k')th argument.''</p>

 <p>The macro form @('(defcong equiv1 equiv2 (fn x1 ... x1) k)') is an
 abbreviation for a @(tsee defthm) of rule-class @(':congruence') that attempts
 to establish that @('equiv2') is maintained by maintaining @('equiv1') in
 @('fn')'s @('k')th argument.  The @(tsee defcong) macro automatically
 generates the general formula shown above.  See @(see defcong).</p>

 <p>The @('memb') example above tells us that @('(memb e x)') is
 propositionally equivalent to @('(memb e y)'), provided @('x') and @('y') are
 @('set-equal').  The outside equivalence is @(tsee iff) and the inside
 equivalence for the second argument is @('set-equal').  If we see a @('memb')
 expression in a propositional context, e.g., as a literal of a @(see clause)
 or test of an @(tsee if) (but not, for example, as an argument to @(tsee
 cons)), we can rewrite its second argument maintaining @('set-equality').  For
 example, a rule stating the commutativity of @(tsee append) (modulo
 set-equality) could be applied in this context.  Since equality is a
 refinement of all equivalence relations, all equality rules are always
 available.  See @(see refinement).</p>

 <p>All known congruence rules about a given outside equivalence and @('fn')
 can be used independently.  That is, consider two congruence rules with the
 same outside equivalence, @('equiv'), and about the same function @('fn').
 Suppose one says that @('equiv1') is the inside equivalence for the first
 argument and the other says @('equiv2') is the inside equivalence for the
 second argument.  Then @('(fn a b)') is @('equiv') <tt>(fn a' b')</tt>
 provided @('a') is @('equiv1') to @('a'') and @('b') is @('equiv2') to
 @('b'').  This is an easy consequence of the transitivity of @('equiv').  It
 permits you to think independently about the inside equivalences.</p>

 <p>Furthermore, it is possible that more than one inside equivalence for a
 given argument slot will maintain a given outside equivalence.  For example,
 @('(length a)') is equal to <tt>(length a')</tt> if @('a') and @('a'') are
 related either by @('list-equal') or by @(tsee string-equal).  You may prove
 two (or more) congruence rules for the same slot of a function.  The result is
 that the system uses a new, ``generated'' equivalence relation for that slot
 with the result that rules of both (or all) kinds are available while
 rewriting.  See @(see geneqv) for a discussion of how generated equivalence
 relations are derived using congruence rules and how generated equivalence
 relations are represented.</p>

 <p>Congruence rules can be @(see disable)d.  For example, if you have two
 different inside equivalences for a given argument position and you find that
 the @(':')@(tsee rewrite) rules for one are unexpectedly preventing the
 application of the desired rule, you can disable the rule that introduced the
 unwanted inside equivalence.</p>

 <p><b>NOTE</b> however that unlike other rules, the tracking of congruence
 rules is incomplete.  Specifically: when congruence rules are used by the
 rewriter as it descends through terms, to maintain the generated equivalence
 relation used for rewriting, ACL2 does not track the congruence rules that are
 used, even though it is relevant that they are all @(see enable)d.  Congruence
 rules that are used only in this way will therefore not appear in the @(see
 summary).</p>

 <p><i>Remark on Replacing IFF by EQUAL.</i> You may encounter a warning
 suggesting that a congruence rule ``can be strengthened by replacing the
 second equivalence relation, IFF, by EQUAL.''  Suppose for example that this
 warning occurs when you submit the following rule:</p>

 @({
  (defcong equiv1 iff (fn x y) 2)
 })

 <p>which is shorthand for the following:</p>

 @({
  (defthm equiv1-implies-iff-fn-2
         (implies (equiv1 y y-equiv)
                  (iff (fn x y) (fn x y-equiv)))
         :rule-classes (:congruence))
 })

 <p>The warning is telling you that ACL2 was able to deduce that @('fn') always
 returns a Boolean, and hence a trivial but useful consequence is obtained by
 replacing @(tsee iff) by @(tsee equal) &mdash;</p>

 @({
  (defcong equiv1 equal (fn x y) 2)
 })

 <p>&mdash; which is shorthand for the following:</p>

 @({
  (defthm equiv1-implies-equal-fn-2
         (implies (equiv1 y y-equiv)
                  (equal (fn x y) (fn x y-equiv)))
         :rule-classes (:congruence))
 })

 <p>If you have difficulty proving the latter directly, you can derive it from
 the former by giving a suitable hint, minimally as follows.</p>

 @({
  (defcong equiv1 equal (fn x y) 2
    :hints (("Goal"
             :use equiv1-implies-iff-fn-2
             :in-theory
             (union-theories '((:type-prescription fn))
                             (theory 'minimal-theory)))))
 })

 <p>By heeding this warning, you may avoid unnecessary @(tsee double-rewrite)
 warnings later.  We now explain why, but see @(see double-rewrite) for
 relevant background material.</p>

 <p>For example, suppose you have proved the ``@('iff')'' version of the
 congruence rule above, and later you submit the following rewrite rule.</p>

 @({
  (defthm equal-list-perm
    (implies (equiv1 x y)
             (fn x y)))
 })

 <p>Since @('fn') is known to return a Boolean, ACL2 performs an optimization
 that stores this rule as though it were the following.</p>

 @({
  (defthm equal-list-perm
    (implies (equiv1 x y)
             (equal (fn x y) t)))
 })

 <p>Thus, if ACL2's rewriter sees a term @('(fn a b)') in a context where the
 equivalence relation @(tsee iff) is not being maintained, then it cannot use
 rule @('equiv1-implies-iff-fn-2'), so it rewrites argument @('a') without the
 benefit of knowing that it suffices to maintain @('equiv1'); and then it
 caches the result.  When ACL2 subsequently attempts to relieve the hypothesis
 @('(equiv1 x y)'), it will rewrite @('x') simply by returning the rewritten
 value of @('a') from the result cache.  This is unfortunate if @('a') could
 have been rewritten more completely under maintenance of the equivalence
 relation @('equiv1') &mdash; which is legal in the hypothesis since @('a') is
 an argument of @('equiv1'), which is an @(see equivalence) relation.  The user
 who observes the warning from rule @('equiv1-implies-iff-fn-2'), and replaces
 it with @('equiv1-implies-equal-fn-2'), will avoid this unfortunate
 case.</p>")

(defxdoc conjugate
  :parents (numbers acl2-built-ins)
  :short "Complex number conjugate"
  :long "<p>@('Conjugate') takes an ACL2 number as an argument, and returns its
 complex conjugate (i.e., the result of negating its imaginary part.).</p>

 <p>@('Conjugate') is a Common Lisp function.  See any Common Lisp
 documentation for more information.</p>

 @(def conjugate)")

(defxdoc cons
  :parents (conses acl2-built-ins)
  :short "Pair and list constructor"
  :long "<p>@('(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 additional element @('x') on the front.</p>")

(defxdoc cons-count-bounded
  :parents (conses acl2-built-ins)
  :short "Count the number of conses (up to a limit)"
  :long "<p>The call @('(cons-count-bounded x)') returns the number of cons
 nodes in @('x') (without accounting for sharing), but truncated above by the
 value of @('(fn-count-evg-max-val)'), which is 200,000 as of this
 writing.</p>")

(defxdoc cons-subtrees
  :parents (fast-alists acl2-built-ins)
  :short "Build a fast alist whose keys are the subtrees of X"
  :long "<p>@('(cons-subtrees x nil)') builds a fast alist that associates each
subtree of X with T, without duplication.</p>

 @(def cons-subtrees)")

(defxdoc cons-with-hint
  :parents (conses acl2-built-ins)
  :short "Alternative to @(tsee cons) that tries to avoid consing when a
 suitable @('cons') structure is provided as a hint."
  :long "<p>This is a special purpose function that is intended to help with
 reducing the memory usage of functions that modify existing cons tree
 structures.  Also see @(see hons) for a way to share @(see cons) structures;
 however, @('cons-with-hint') is likely much cheaper than @('hons') and hence
 can be useful for reducing consing without the overhead of @('hons').</p>

 <p>Logically @('(cons-with-hint x y hint)') is just @('(cons x y)'); @('hint')
 is completely irrelevant and ignored.  We generally expect that
 @('cons-with-hint') will just be left @(see enable)d, so you should never have
 to reason about it.</p>

 <p>But @('cons-with-hint') has a special raw Common Lisp definition that tries
 to avoid consing by using your @('hint').  Specifically: if @('hint') is the
 cons @('(x . y)'), then @('hint') is returned without creating a new cons.
 Equality checking against @('x') and @('y') is done using @(tsee eql), which
 makes it a fast but incomplete check for equality.</p>

 <p>What good is this?  A fairly common operation in ACL2 is to ``change'' an
 existing data structure by consing together a new structure that is similar to
 it, but perhaps with some subtrees replaced.  In many cases, some portion of
 the structure does not need to change.</p>

 <p>For instance, consider a function like @(tsee remove-equal), which updates
 a list by removing all copies of some element from it.  The definition of
 @('remove-equal') is as follows (in the logic; it has a slightly different
 definition in raw Lisp).</p>

 @(def remove-equal)

 <p>You can see that if @('l') doesn't have any copies of @('x'), this function
 will essentially make a fresh copy of the whole list @('x').  That could waste
 a lot of memory when @('x') is long.  The choice was made to define
 @('remove-equal') ``under the hood'' to call Common Lisp's function,
 @('remove'); but it is easy to write a new version of @('remove-equal') that
 uses @('cons-with-hint'):</p>

 @({
 (defun remove-equal-with-hint (x l)
   (declare (xargs :guard (true-listp l)))
   (mbe :logic (remove-equal x l)
        :exec (cond ((endp l) nil)
                    ((equal x (car l))
                     (remove-equal-with-hint x (cdr l)))
                    (t
                     (cons-with-hint (car l)
                                     (remove-equal-with-hint x (cdr l))
                                     l)))))
 })

 <p>This new version avoids consing in the case that we are not dropping an
 element.  For example, at the time of this writing, we found the following
 memory usages on our copy of ACL2 built on CCL:</p>

 @({
 :q

 ;; 16 MB of memory allocated
 (let ((list (make-list 1000 :initial-element 0)))
   (time (loop for i from 1 to 1000 do (remove-equal i list))))

 ;; 0 MB of memory allocated
 (let ((list (make-list 1000 :initial-element 0)))
   (time (loop for i from 1 to 1000 do (remove-equal-with-hint i list))))
 })

 <p>This memory usage is not very surprising when you consider that the list
 does not change when no removal takes place.  For example (still in raw
 Lisp):</p>

 @({
 ? (let ((x '(a b c d e))) (eq x (remove-equal-with-hint 3 x)))
 T
 ?
 })

 <p>Note that ACL2 asks Lisp to inline calls of @('cons-with-hint'), so there
 will likely be no function call overhead for using @('cons-with-hint').</p>")

(defxdoc conservativity-of-defchoose
  :parents (defchoose)
  :short "Proof of conservativity of @(tsee defchoose)"
  :long "<p>This documentation topic provides underlying theory.  It is of
 theoretical interest only; it has no relationship to the effective use of
 ACL2.</p>

 <p>The argument below for the conservativity of @(see defchoose) replaces the
 terse and somewhat misleading reference to a forcing argument in Appendix B of
 the paper by ACL2 authors Kaufmann and Moore, ``Structured Theory Development
 for a Mechanized Logic'' (Journal of Automated Reasoning 26, no. 2 (2001),
 pp. 161&ndash;203).</p>

 <p>Our basic idea is to take a (countable) first-order structure for ACL2,
 M, together with a function symbol, f, introduced by @(see defchoose), and
 find a way to expand M with an interpretation of f (without changing the
 universe of M) so that e0-induction continues to hold in the expansion.  A
 remark at the end of this documentation topic shows why care is necessary.  A
 concept called ``forcing'', originally introduced by Paul Cohen for set
 theory, has long since been adapted by logicians (in a simplified form) to
 model theory.  This simplified model-theoretic forcing provides the means for
 making our careful expansion.</p>

 <p>The forcing argument presented below is intended to be completely
 self-contained for those familiar with basic first-order logic and ACL2; in
 particular, see @(see defchoose).  No background in forcing (model-theoretic
 or otherwise) is expected, though we do expect a rudimentary background in
 first-order logic and familiarity with the following.</p>

 <p>Preliminaries.  We write s[p&lt;-p0] to denote the result of extending or
 modifying the assignment s by binding p to p0.  Now let A be a subset of the
 universe U of a first-order structure M.  A is said to be ``first-order
 definable with parameters'' in M if for some formula phi, variable x, and
 assignment s binding the free variables of phi except perhaps for x, A = {a
 \in U: M |= phi[s[x&lt;-a]]}.  Note that we are writing ``\in'' to denote
 set membership.  Finally, we indicate the end of a proof (or of a theorem
 statement, when the proof is omitted) with the symbol ``-|''.</p>

 <p>We gratefully acknowledge very helpful feedback from John Cowles, who found
 several errors in a draft of this note and suggested the exercises.  We also
 thank Ruben Gamboa for helpful feedback, and we thank Jim Schmerl for an
 observation that led us directly to this proof in the first place.</p>

 <p>We are given a consistent first-order theory T, extending the ACL2
 ground-zero theory, that satisfies the e0-induction scheme.  We wish to show
 that the extension of T by the following arbitrary defchoose event is
 conservative, where g is a new function symbol.</p>

 @({
       (defchoose g <bound-vars> <free-vars> <body>)
 })

 <p>Note that by ``the extension of T'' here we mean the extension of T by not
 only the new defchoose axiom displayed just below, but also the addition of
 e0-induction axioms for formulas in the expanded language obtained by
 including the new defchoose function symbol, g.</p>

 @({
       <body> -> (LET <bound-vars> = g(<free-vars>) in <body>)
 })

 <p>By definition of conservativity, since proofs are finite, it clearly
 suffices to consider an arbitrary finite subset of T.  Then by the
 completeness, soundness, and downward Lowenheim-Skolem theorems of first-order
 logic, it suffices to show that an arbitrary countable model of T can be
 expanded (i.e., by interpreting the new symbol g without changing the universe
 of the model) to a model of the corresponding defchoose axiom above, in which
 all e0-induction axioms hold in the language of that model (i.e., the expanded
 language).</p>

 <p>Below, we will carry out a so-called <i>forcing</i> construction, which
 allows us to expand any countable model M of T to a model M[G] for the
 expanded language that satisfies e0-induction (in the expanded language) and
 also satisfies the axiom displayed above, generated from the defchoose event.
 The ideas in this argument are standard in model theory; no novelty is claimed
 here.</p>

 <p>Fix a countable model M of a theory T that satisfies e0-induction for its
 countable language and extends the ACL2 ground-zero theory.  Also fix the
 above defchoose axiom, where g is not in the language of T.</p>

 <p>We start by defining a partial order P as follows.  Let Nb and Nf be the
 lengths of &lt;bound-vars&gt; and &lt;free-vars&gt;, respectively.  P consists
 of all fn in M such that the following formula is true in M.  Roughly
 speaking, it says that fn is a finite function that witnesses, on its domain,
 the requirement above for g.</p>

 @({
         alistp(fn) &
         no-duplicatesp-equal(strip-cars(fn)) &
         (forall <bound-vars>, <free-vars> .
            (member-equal(cons(<free-vars>,<bound-vars>), fn) ->
             (length(<bound-vars>) = Nb &
              length(<free-vars>)  = Nf &
              ((exists <bound-vars> . <body>) ->
               (LET <bound-vars> = g(<free-vars>) in <body>)))))
 })

 <p>P is ordered by subset, i.e., we say that p2 <i>extends</i> p1 if p1 is a
 subset (not necessarily proper) of p2 (more precisely, M |=
 subsetp-equal(p1,p2)).</p>

 <p>Remark.  The original argument in Appendix B of the aforementioned paper
 can essentially be salvaged, as we now show.  The key observation is that the
 particular choice of P is nearly irrelevant for the argument that follows
 below.  In particular, we can instead define P to consist of finite one-one
 functions with domain contained in the set of natural numbers.  More
 precisely, consider the following definitions.</p>

 @({
       (defun function-p (fn)
         (and (alistp fn)
              (no-duplicatesp-equal (strip-cars fn))))

       (defun nat-function-p (x)
         (and (function-p x)
              (nat-listp (strip-cars x))))
 })

 <p>and define an inverse function on alists as follows.</p>

 @({
       (defun inverse (fn)
         (if (endp fn)
             nil
           (cons (cons (cdar fn) (caar fn))
                 (inverse (cdr fn)))))
 })

 <p>Then P may instead be defined to consist of those fn for which
 nat-function-p(fn) &amp; function-p(inverse(fn)).  With this alternate
 definition of P, the argument below then goes through virtually unchanged, and
 we get an expansion M[G] of M in which there is a definable enumeration of the
 universe.  The conservativity of defchoose then follows easily because the
 function being introduced can be defined explicitly using that enumeration
 (namely, always pick the least witness in the sense of the enumeration).</p>

 <p>End of Remark.</p>

 <p>Next we present the relevant forcing concepts from model theory.</p>

 <p>A <i>dense</i> subset of P is a subset D of P such that for every p \in P,
 there is d \in D such that d extends p.  A subset G of P is <i>generic</i>
 with respect to a collection Ds of dense subsets of P, also written ``G is
 Ds-generic,'' if G is closed under subset (if p2 \in G and p2 extends p1 then
 p1 \in G), G is pairwise compatible (the union-equal of any two elements of G
 is in G), and every set in Ds has non-empty intersection with G.</p>

 <p>For p \in P, we say that a subset D of P is <i>dense beyond</i> p if for
 all p1 extending p there exists p2 extending p1 such that p2 \in D.  This
 notion makes sense even for D not a subset of P if we treat elements of D not
 in P as nil.</p>

 <p>Proposition 1.  For any partial order P and countable collection Ds of
 dense subsets of P, there is a Ds-generic subset of P.</p>

 <p>Proof.  Let Ds = {D0,D1,D2,...}.  Define a sequence &lt;p_0,p_1,...&gt;
 such that for all i, p_i \in Di and p_(i+1) extends p_i.  Let G = {p \in P:
 for some i, pi extends p}.  Then G is Ds-generic. -|</p>

 <p>Note that P is first-order definable (with parameters) in M.  Let Df be the
 set of dense subsets of P that are first-order definable (with parameters) in
 M.  A standard argument shows there are only countably many first-order
 definitions with parameters in a countable model M whose language is countable
 &mdash; for example, we can Goedel number all terms and then all formulas
 &mdash; hence, Df is countable.</p>

 <p>By Proposition 1, let G be Df-generic.  Notice that for any list x of
 length Nf in M, the set of elements f of P for which x is in the domain of f
 is dense and first-order definable.  We may thus define a function g0 as
 follows: g0(x_1,...,x_Nf) = y if there is some element of G containing the
 pair ((x_1 ... x_Nf) . y).  It is easy to see that g0 is a total function on
 M.  Let L be the language of T and let L[g] be the union of L with a set
 containing a single new function symbol, g.  Let M[G] be the expansion of M to
 L[g] obtained by interpreting g to be g0 (see also Proposition 5 below).</p>

 <p>So now we have fixed M, P, Df, G, and g0, where G is Df-generic.</p>

 <p>Proposition 2.  Let Df be the set of dense subsets of P that are
 first-order definable (with parameters) in M.  Suppose that p \in G and D
 \in Df.  Then for some q \in G extending p, q \in D.</p>

 <p>Proof.  Let D0 be the set of p' \in D that either extend p or have no
 extension in D that extends p.  We leave it as a straightforward exercise to
 show that D0 is dense, and D0 is clearly first-order definable (with
 parameters) in M.  So by genericity of G, we may pick q \in D0 such that q
 \in G.  Thus q \in D.  By definition of generic, some extension q1 of both p
 and q belongs to G.  Pick q2 \in D extending q1; thus q has an extension in D
 that extends p (namely, q2), so by definition of D0, q extends p. -|</p>

 <p>Definition of forcing.  Let phi(x1,...,xk) be a first-order formula in L[g]
 and let p \in P.  We define a formula of L, denoted ``p ||- phi'' (``p forces
 phi''), by recursion on phi (in the metatheory) as follows.  (Here, we view
 ``or'' and ``forall'' as abbreviations.)</p>

 <blockquote><p>If phi is atomic, then let phi'(A) be the result of replacing,
   inside-out, each subterm of the form g(x_1,...,x_Nb) with the term (cdr
   (assoc-equal (list x_1 ... x_Nb) A)), where A is neither p nor a variable
   occurring in phi.  Then p ||- phi is defined as follows: ``The set {A \in
   P: A extends p and phi'(A)} is dense beyond p''.  That is, p ||- phi is the
   following formula:</p>

 @({
      (forall p1 \in P extending p)
       (exists p2 \in P extending p1) phi'(p2).
 })

 <p>p ||- ~phi is: (forall p' \in P extending p) ~(p' ||- phi)</p>

 <p>p ||- phi_1 &amp; phi_2 is: (p ||- phi_1) &amp; (p ||- phi_2)</p>

 <p>p ||- (exists x) phi is: (exists x) (p ||- phi)</p></blockquote>

 <p>We will need the following definition later.</p>

 <p>Definition.  p ||-w phi (p <i>weakly forces</i> phi) is an abbreviation for
 p ||- ~~phi.</p>

 <p>The following exercises were suggested by John Cowles as a means for
 gaining familiarity with the definition of forcing.</p>

 <p>Exercise 1. Consider the formula (phi_1 OR phi_2) as an abbreviation for
 ~(~phi_1 &amp; ~phi_2), Show that p ||- (phi_1 OR phi_2) is equivalent to the
 following.</p>

 @({
       (forall p' \in P extending p) (exists p'' \in P extending p')
        ((p'' ||- phi_1) OR (p'' ||- phi_2))
 })

 <p>Exercise 2. Consider the formula (forall x)phi as an abbreviation for
 ~(exists x)~phi, Show that p ||- (forall x)phi is equivalent to the
 following.</p>

 @({
       (forall x)
        (forall p1 \in P extending p)
         (exists p2 \in P extending p1) (p2 ||- phi).
 })

 <p>Exercise 3. Prove that p ||-w phi is equivalent to the following.</p>

 @({
       (forall p' \in P extending p)
        (exists p'' \in P extending p') (p'' ||- phi).
 })

 <p>Exercise 4. Let phi be a formula of L[g].  Prove: M |= (p ||-
      phi)[s[p&lt;-p0]] implies M |= (p ||-w phi)[s[p&lt;-p0]].</p>

 <p>Exercise 5. Let phi be a formula of L[g].  Prove: M |= (p ||-
      ~phi)[s[p&lt;-p0]] iff M |= (p ||-w ~phi)[s[p&lt;-p0]].</p>

 <p>[End of exercises.]</p>

 <p>The definition of forcing stipulates how to view ``p ||- phi(x1,...,xk)''
 as a new formula theta(p,x1,...,xk).  That is, ``||-'' transforms formulas, so
 for any first-order formula phi, ``p ||- phi'' is just another first-order
 formula.  That observation shows that a formula such as ((p ||- phi) OR (p ||-
 ~phi)) is really just another first-order formula.  The following proposition
 thus follows easily.</p>

 <p>Proposition 3. For any formula phi of L[g], {p0: M |= ((p ||- phi) OR (p
 ||- ~phi))[s[p&lt;-p0]]]} is a dense subset of P, which (since it is
 first-order definable with parameters in M) intersects G. -|</p>

 <p>The following proposition is easily proved by a structural induction on
 phi, and is left to the reader.</p>

 <p>Proposition 4. Let phi be a formula of L[g].  Suppose p0 \in P, p1
 \in P,<br/>

 M |= (p ||- phi)[s[p&lt;-p0]],<br/>

 and p1 extends p0.  Then<br/>

 M |= (p ||- phi)[s[p&lt;-p1]]. -|</p>

 <p>We will also need the following.</p>

 <p>Proposition 5. The following is dense for any finite set S of Nf-tuples: {p
 \in P: for some &lt;x_1 ... x_Nf&gt; \in S, (list x_1 ... x_Nf) \in
 strip-cars(p)}.  Thus, the function g0 is a total function. -|</p>

 <p>The next lemma tells us that the sentences true in M[G] are those that are
 forced by an element of G.</p>

 <p>Truth Lemma.  Let phi be a formula in L[g], let s be an assignment to the
 free variables of phi, and let p be a variable not in the domain of s.  Then
 M[G] |= phi[s] iff for some p0 \in G, M |= (p ||- phi)[s[p&lt;-p0]].</p>

 <p>Proof.  The proof is by induction on the structure of phi.  First suppose
 phi is atomic.  Let D* be the set of elements p0 \in P such that every
 assoc-equal evaluation from the definition of forcing phi returns a pair when
 A is bound to p0.  (Intuitively, this means that p0 is a sufficiently large
 approximation from any G containing p0 to make sense of phi in M[G].)  We make
 the following claim.</p>

 @({
  (*)   For all p0 \in G such that p0 \in D*,
        M[G] |= phi[s] iff M |= (p ||- phi)[s[p<-p0]].
 })

 <p>To prove the claim, fix p0 in both G and D*, and recall the function g0
 constructed from G in the definition of M[G].  Suppose that t_1, ..., t_Nf are
 terms and g(t_1, ..., t_Nf) is a subterm of phi.  Then s assigns a value in M
 to each of the t_i.  Let a_i be the value assigned by s to t_i.  Then g0(a_1,
 ..., a_Nf) = (cdr (assoc-equal (list a_1 ... a_Nf) p0)), as the assoc-equal is
 a pair (since p0 \in D*) and has the indicated value (because p0 \in G).  It
 follows by the definition of formula phi' in the definition of forcing:</p>

 @({
       M[G] |= phi[s]  iff  M |= phi'(p)[s[p<-p0]]
 })

 <p>Moreover, because p0 \in D* it is clear that this holds if p0 is replaced
 by an arbitrary extension of p0.  Then (*) easily follows.</p>

 <p>By Proposition 5, D* is dense, so there is some p0 in the intersection of
 D* and G.  The forward direction of the conclusion then follows by (*).  The
 reverse direction is clear from (*) by application of Proposition 2 to D* and
 Proposition 4.</p>

 <p>Next, suppose M[G] |= ~phi[x].  Then it is not the case that M[G] |= phi,
 so by the inductive hypothesis, there is no p0 \in G for which M |= (p ||-
 phi)[s[p&lt;-p0]].  By Proposition 3, there is p0 \in G for which M |= (p ||-
 ~phi)[s[p&lt;-p0]].  For the other direction, suppose it is not the case that
 M[G] |= ~phi[s].  So M[G] |= phi[s], and by the inductive hypothesis, there is
 p0 \in G for which M |= (p ||- phi)[s[p&lt;-p0]].  It follows that there is
 no p1 \in G for which M |= (p ||- ~phi)[s[p&lt;-p1]], since from such p1 we
 can find a common extension p2 of p0 and p1 (since G is generic), and since p2
 extends p0 then by Proposition 4, M |= (p ||- phi)[s[p&lt;-p2]], contradicting
 (by definition of forcing) M |= (p ||- ~phi)[s[p&lt;-p1]] since p2 extends
 p1.</p>

 <p>The case (phi_1 &amp; phi_2) follows easily from the inductive hypothesis.
 For the forward direction, apply Proposition 4 and the observation that by
 genericity, if p0 \in G and p1 \in G then p0 and p1 have a common extension
 in G.</p>

 <p>Finally, the case (exists x) phi follows trivially from the inductive
 hypothesis. -|</p>

 <p>Truth Lemma Corollary.  The Truth Lemma holds with ||-w replacing ||-.</p>

 <p>Proof.  This is clear by applying the Truth Lemma to ~~phi. -|</p>

 <p>Here is our main theorem.  Recall that all first-order theories in our ACL2
 context satisfy the e0-induction scheme.</p>

 <p>Theorem.  M[G] satisfies e0-induction.</p>

 <p>Proof.  We consider an arbitrary instance of e0-induction in L[g], stated
 using a strict well-founded relation &lt;| and a formula phi.  We write phi(y)
 to indicate that y may be among the free variables of phi, and phi(y&lt;-x) to
 denote the result of substituting x for y in phi.</p>

 @({
    theta:   (forall y) [((forall x <| y) phi(y<-x)) -> phi(y)]
          -> (forall y) phi(y)
 })

 <p>Our goal is to prove that theta holds in M[G].</p>

 <p>Below, we abuse notation by leaving assignments implicit and by writing ``p
 ||- phi(y0)'' to signify that the formula (p ||- phi(y)) is true in M under
 the extension of the explicit assignment that binds y to y0.  We believe that
 the intended meaning will be clear.</p>

 <p>Consider the following set D.</p>

 @({
    D = {p \in P: either p ||-w phi(y0) for all y0,
                  or else
                  for some y0, p ||- ~phi(y0) and
                               for all y1 <| y0 p ||-w phi(y1)}.
 })

 <p>The set D is clearly first-order definable (with parameters) in M.  We
 claim that D is a dense subset of P.  For suppose p0 \in P; we find p1 \in D
 extending p0, as follows.  If p0 ||-w phi(y0) for all y0, then we may take p1
 to be p0.  Otherwise, by definition of ||-w and ||-, there is some y0 such
 that for some extension p0' of p0, p0' ||- ~phi(y0).  Pick a &lt;|-minimal
 such y0, and correspondingly pick p1 so that p1 extends p0 and p1 ||-
 ~phi(y0).  In order to show that p1 \in D, it remains to show that for all y1
 &lt;| y0, p1 ||-w phi(y1), i.e., there is no q extending p1 such that q ||-
 ~phi(y1).  This is indeed the case since otherwise q and y1 would contradict
 the &lt;|-minimality of y0.</p>

 <p>Applying the genericity of G and just-proved density of D, pick p0 \in G
 such that p0 \in D.  If p0 ||-w phi(y0) for all y0, then by the Truth Lemma
 Corollary, M[G] |= phi(y0) for all y0, and thus M[G] |= theta.  Otherwise,
 since p0 \in D we may choose y0 such that p0 ||- ~phi(y0) and for all y1
 &lt;| y0, p0 ||-w phi(y1).  By the Truth Lemma and its corollary, since p0
 \in G we have:</p>

 @({
  (1)   M[G] |= ~phi(y0).
  (2)   For all y1 <| y0, M[G] |= phi(y1).
 })

 <p>It follows that the antecedent of theta is false in M[G], as witnessed by y
 = y0; thus M[G] |= theta. -|</p>

 <p>Remark.  We close by returning, as promised above, to the question of why
 so much care is necessary in constructing an expansion of M.  We assume
 familiarity here with the notion of a ``non-standard'' natural number of M,
 i.e., one that is greater than the interpretation of any term that has the
 form (+ 1 1 1 ... 1).  Here is a very simple example that illustrates the need
 for some care.  Consider the following event, which introduces a function foo
 with the following property: for all x, if natp(x) then natp(foo(x)).</p>

 @({
       (defchoose foo (y) (x)
         (implies (natp x) (natp y)))
 })

 <p>Certainly we can build a model of the above property from a model M of the
 ground-zero theory, by interpreting foo so that for all x for which M
 satisfies natp(x), foo(x) is also a natp in M.  But suppose we start with a
 non-standard model M of the ground-zero theory, and we happen to define foo(x)
 to be 1 for all non-standard natural numbers x and 0 for all other x.  The
 resulting expansion of M will not satisfy the e0-induction scheme or even the
 ordinary natural number induction scheme: foo(0)=0 holds in that expansion as
 does the implication foo(n)=0 =&gt; foo(n+1)=0 for every natural number n of
 M, standard or not; and yet foo(k)=0 fails for every non-standard natural
 number k of M.</p>")

(defxdoc conses
  :parents (programming)
  :short "A <b>cons</b> is an ordered pair.  In ACL2, data structures like
 @(see lists), @(see alists), etc., are made up of conses.")

(defxdoc consp
  :parents (conses acl2-built-ins)
  :short "Recognizer for @(see cons) pairs"
  :long "<p>@('(consp x)') is true if and only if @('x') is a @(see cons)
 pair.</p>")

(defxdoc constraint
  :parents (encapsulate)
  :short "Restrictions on certain functions introduced in @(tsee encapsulate) @(see events)"
  :long "<p>Suppose that a given theorem, @('thm'), is to be functionally
 instantiated using a given functional substitution, @('alist').  (See @(see
 lemma-instance), or for an example, see @(see
 functional-instantiation-example).)  What is the set of proof obligations
 generated?  It is the set obtained by applying @('alist') to all terms,
 @('tm'), such that (a) @('tm') mentions some function symbol in the domain of
 @('alist'), and (b) either (i) @('tm') is the ``constraint'' (see below) on a
 function symbol ancestral in @('thm') or in some @(tsee defaxiom) or (ii)
 @('tm') is the body of a @(tsee defaxiom).  Here, a function symbol is
 ``ancestral'' in @('thm') if either it occurs in @('thm'), or it occurs in the
 definition of some function symbol that occurs in @('thm'), and so on.</p>

 <p>The remainder of this note explains what we mean by ``constraint'' in the
 words above.  For a utility that obtains the constraint for a given function
 symbol, see @(see constraint-info).  For help in dealing with failures to
 prove constraint obligations generated by the @(':functional-instance')
 hint (see @(see hints)), see @(tsee set-constraint-tracking).</p>

 <p>In a certain sense, function symbols are introduced in essentially two
 ways.  The most common way is to use @(tsee defun) (or when there is mutual
 recursion, @(tsee mutual-recursion) or @(tsee defuns)).  There is also a
 mechanism for introducing ``witness functions''; see @(see defchoose).  The
 documentation for these @(see events) describes the axioms they introduce,
 which we will call here their ``definitional axioms.''  These definitional
 axioms are generally the constraints on the function symbols that these axioms
 introduce.</p>

 <p>However, when a function symbol is introduced in the scope of an @(tsee
 encapsulate) event, its constraints may differ from the definitional axioms
 introduced for it.  For example, suppose that a function's definition is
 @(tsee local) to the @(tsee encapsulate); that is, suppose the function is
 introduced in the @(see signature) of the @(tsee encapsulate).  Then its
 constraints include, at the least, those non-@(tsee local) theorems and
 definitions in the @(tsee encapsulate) that mention the function symbol.</p>

 <p>Actually, it will follow from the discussion below that if the @(see
 signature) is empty for an @(tsee encapsulate), then the constraint on each of
 its new function symbols is exactly the definitional axiom introduced for it.
 Intuitively, we view such @('encapsulates') just as we view @(tsee
 include-book) @(see events).  But the general case, where the @(see signature)
 is not empty, is more complicated.</p>

 <p>In the discussion that follows we describe in detail exactly which
 constraints are associated with which function symbols that are introduced in
 the scope of an @(tsee encapsulate) event.  In order to simplify the
 exposition we make two cuts at it.  In the first cut we present an
 over-simplified explanation that nevertheless captures the main ideas.  In the
 second cut we complete our explanation by explaining how we view certain @(see
 events) as being ``lifted'' out of the @(tsee encapsulate), resulting in a
 possibly smaller @(tsee encapsulate), which becomes the target of the
 algorithm described in the first cut.</p>

 <p>At the end of this note we present an example showing why a more naive
 approach is unsound.</p>

 <p>Finally, before we start our ``first cut,'' we note that any information
 you want ``exported'' outside an @(tsee encapsulate) event must be there as an
 explicit definition or theorem.  For example, even if a function @('foo') has
 output type @('(mv t t)') in its @(see signature), the system will not know
 @('(true-listp (foo x))') merely on account of this information.  Thus, if you
 are using functions like @('foo') (constrained @(tsee mv) functions), then you
 may find it useful to prove (inside the @('encapsulate'), to be exported) a
 @(':')@(tsee type-prescription) rule for the constrained function, for
 example, the @(':')@(tsee type-prescription) rule @('(true-listp (foo
 x))').</p>

 <p><i>First cut at constraint-assigning algorithm.</i> Consider the set of
 formulas introduced by all @(see events) in the scope of an @(tsee
 encapsulate):</p>

 <ul>

 <li>for every @(tsee defthm) and @(tsee defaxiom) event, include its formula
 as well as the formulas of all its corollaries;</li>

 <li>for every @(tsee defun) event, include the formula that equates the body
 with the application of the function applied to the formals;</li>

 <li>for every @('defchoose') event, include the axiom that it adds (see @(see
 defchoose));</li>

 <li>and so on, including axioms added by @(tsee defpkg) and (recursively) any
 subsidiary @('encapsulate') events.</li>

 </ul>

 <p>Then quite simply, all such formulas are conjoined, and each function
 symbol introduced by the @(tsee encapsulate) is assigned that conjunction as
 its constraint.</p>

 <p>Clearly this is a rather severe algorithm.  Let us consider two possible
 optimizations in an informal manner before presenting our second cut.</p>

 <p>Consider the (rather artificial) event below.  The function @('before1')
 does not refer at all, even indirectly, to the locally-introduced function
 @('sig-fn'), so it is unfortunate to saddle it with constraints about
 @('sig-fn').</p>

 @({
  (encapsulate
   (((sig-fn *) => *))

   (defun before1 (x)
     (if (consp x)
         (before1 (cdr x))
       x))

   (local (defun sig-fn (x) (cons x x)))

   (defthm sig-fn-prop
     (consp (sig-fn x)))
   )
 })

 <p>We would like to imagine moving the definition of @('before1') to just in
 front of this @(tsee encapsulate), as follows.</p>

 @({
  (defun before1 (x)
    (if (consp x)
        (before1 (cdr x))
      x))

  (encapsulate
   (((sig-fn *) => *))

   (local (defun sig-fn (x) (cons x x)))

   (defthm sig-fn-prop
     (consp (sig-fn x)))
   )
 })

 <p>Thus, we will only assign the constraint @('(consp (sig-fn x))'), from the
 theorem @('sig-fn-prop'), to the function @('sig-fn'), not to the function
 @('before1').</p>

 <p>More generally, suppose an event in an @(tsee encapsulate) event does not
 mention any function symbol in the @(see signature) of the @(tsee
 encapsulate), nor any function symbol that mentions any such function symbol,
 and so on.  (We might say that no function symbol from the @(see signature) is
 an ``ancestor'' of any function symbol occurring in the event.)  Then we
 imagine moving the event, so that it appears in front of the @(tsee
 encapsulate).  We don't actually move it, but we pretend we do when it comes
 time to assign constraints.  Thus, such definitions only introduce
 definitional axioms as the constraints on the function symbols being defined.
 In the example above, the event @('sig-fn-prop') introduces no constraints on
 function @('before1').</p>

 <p>Once this first optimization is performed, we have in mind a set of
 ``constrained functions.''  These are the functions introduced in the @(tsee
 encapsulate) that would remain after moving some of them in front, as
 indicated above.  Consider the collection of all formulas introduced by the
 @(tsee encapsulate), except the definitional axioms, that mention these
 constrained functions.  So for example, in the event below, no such formula
 mentions the function symbol @('after1').</p>

 @({
  (encapsulate
   (((sig-fn *) => *))

   (local (defun sig-fn (x) (cons x x)))

   (defthm sig-fn-prop
     (consp (sig-fn x)))

   (defun after1 (x)
     (sig-fn x))
   )
 })

 <p>We can see that there is really no harm in imagining that we move the
 definition of @('after1') out of the @(tsee encapsulate), to just after the
 @(tsee encapsulate).</p>

 <p>Many subtle aspects of this rearrangement process have been omitted.  For
 example, suppose the function @('fn') uses @('sig-fn'), the latter being a
 function in the signature of the encapsulation.  Suppose a formula about
 @('fn') is proved in the encapsulation.  Then from the discussion above
 @('fn') is among the constrained functions of the encapsulate: it cannot be
 moved before the encapsulate and it cannot be moved after the encapsulation.
 But why is @('fn') constrained?  The reason is that the theorem proved about
 @('fn') may impose or express constraints on @('sig-fn').  That is, the
 theorem proved about @('fn') may depend upon properties of the witness used
 for @('sig-fn').  Here is a simple example:</p>

 @({
  (encapsulate
   (((sig-fn *) => *))

   (local (defun sig-fn (x) (declare (ignore x)) 0))

   (defun fn (lst)
     (if (endp lst)
         t
         (and (integerp (sig-fn (car lst)))
              (fn (cdr lst)))))

   (defthm fn-always-true
     (fn lst)))
 })

 <p>In this example, there are no @(tsee defthm) events that mention
 @('sig-fn') explicitly.  One might therefore conclude that it is completely
 unconstrained.  But the witness we chose for it always returns an integer.
 The function @('fn') uses @('sig-fn') and we prove that @('fn') always returns
 true.  Of course, the proof of this theorem depends upon the properties of the
 witness for @('sig-fn'), even though those properties were not explicitly
 ``called out'' in theorems proved about @('sig-fn').  It would be unsound to
 move @('fn-always-true') after the encapsulate.  It would also be unsound to
 constrain @('sig-fn') to satisfy just @('fn-always-true') without including in
 the constraint the relation between @('sig-fn') and @('fn').  Hence both
 @('sig-fn') and @('fn') are constrained by this encapsulation and the
 constraint imposed on each is the same and states the relation between the two
 as characterized by the equation defining @('fn') as well as the property that
 @('fn') always returns true.  Suppose, later, one proved a theorem about
 @('sig-fn') and wished to functionally instantiate it.  Then one must also
 functionally instantiate @('fn'), even if it is not involved in the theorem,
 because it is only through @('fn') that @('sig-fn') inherits its constrained
 properties.</p>

 <p>This is a pathological example that illustrate a trap into which one may
 easily fall: rather than identify the key properties of the constrained
 function the user has foreshadowed its intended application and constrained
 those notions.  Clearly, the user wishing to introduce the @('sig-fn') above
 would be well-advised to use the following instead:</p>

 @({
  (encapsulate
   (((sig-fn *) => *))
   (local (defun sig-fn (x) (declare (ignore x)) 0))
   (defthm integerp-sig-fn
     (integerp (sig-fn x))))

  (defun fn (lst)
    (if (endp lst)
        t
      (and (integerp (sig-fn (car lst)))
           (fn (cdr lst)))))

  (defthm fn-always-true
     (fn lst)))
 })

 <p>Note that @('sig-fn') is constrained merely to be an integer.  It is the
 only constrained function.  Now @('fn') is introduced after the encapsulation,
 as a simple function that uses @('sig-fn').  We prove that @('fn') always
 returns true, but this fact does not constrain @('sig-fn').  Future uses of
 @('sig-fn') do not have to consider @('fn') at all.</p>

 <p>Sometimes it is necessary to introduce a function such as @('fn') within
 the @('encapsulate') merely to state the key properties of the undefined
 function @('sig-fn').  But that is unusual and the user should understand that
 both functions are being constrained.</p>

 <p>Another subtle aspect of encapsulation that has been brushed over so far
 has to do with exactly how functions defined within the encapsulation use the
 signature functions.  For example, above we say ``Consider the collection of
 all formulas introduced by the encapsulate, <i>except the definitional
 axioms</i>, that mention these constrained functions.''  We seem to suggest
 that a definitional axiom which mentions a constrained function can be moved
 out of the encapsulation and considered part of the ``post-encapsulation''
 extension of the logical @(see world), if the defined function is not used in
 any non-definitional formula proved in the encapsulation.  For example, in the
 encapsulation above that constrained @('sig-fn') and introduced @('fn') within
 the encapsulation, @('fn') was constrained because we proved the formula
 @('fn-always-true') within the encapsulation.  Had we not proved
 @('fn-always-true') within the encapsulation, @('fn') could have been moved
 after the encapsulation.  But this suggests an unsound rule because whether
 such a function can be moved after the encapsulate depend on whether its
 <i>admission</i> used properties of the witnesses!  In particular, we say a
 function is ``subversive'' if any of its governing tests or the actuals in any
 recursive call involve a function in which the signature functions are
 ancestral.  See @(see infected-constraints) and see @(see
 subversive-recursions).</p>

 <p>(Aside: The definition of @('fn') in the first encapsulation above that
 defines @('fn'), i.e., the encapsulation with @('fn-always-true') inside, is
 subversive because the call of the macro @(tsee AND) expands to a call of
 @('IF') that governs a recursive call of @('fn'), in this case:</p>

 @({
  (defun fn (lst)
    (if (endp lst)
        t
        (if (integerp (sig-fn (car lst)))
            (fn (cdr lst))
          nil))).
 })

 <p>If we switch the order of conjuncts in @('fn'), then the definition of
 @('fn') is no longer subversive, but it still ``infects'' the constraint
 generated for the encapsulation, hence for @('sig-fn'), because
 @('fn-always-true') blocks the definition of @('fn') from being moved back (to
 after the encapsulation).  Also see @(see infected-constraints).  If we both
 switch the order of conjuncts and drop @('fn-always-true') from the
 encapsulation, then the definition of @('fn') is in essence moved back to
 after the encapsulation, and the constraint for @('sig-fn') no longer includes
 the definition of @('fn').  End of aside.)</p>

 <p>Another aspect we have not discussed is what happens to nested
 encapsulations when each introduces constrained functions.  We say an
 @('encapsulate') event is ``trivial'' if it introduces no constrained
 functions, i.e., if its list of signatures is @('nil').  Trivial
 encapsulations are just a way to wrap up a collection of events into a single
 event.</p>

 <p>From the foregoing discussion we see we are interested in exactly how we
 can ``rearrange'' the events in a non-trivial encapsulation &mdash; moving
 some ``before'' the encapsulation and others ``after'' the encapsulation.  We
 are also interested in which functions introduced by the encapsulation are
 ``constrained'' and what the ``constraints'' on each are.  We may summarize
 the observations above as follows, after which we conclude with a more
 elaborate example.</p>

 <p><i>Second cut at constraint-assigning algorithm.</i> First, we focus only
 on non-trivial encapsulations that neither contain nor are contained in
 non-trivial encapsulations.  (Nested non-trivial encapsulations are not
 rearranged at all: do not put anything in such a nest unless you mean for it
 to become part of the constraints generated.)  Second, in what follows we only
 consider the non-@('local') events of such an @('encapsulate'), assuming that
 they satisfy the restriction of using no locally defined function symbols
 other than the signature functions.  Given such an @('encapsulate') event,
 move, to just in front of it and in the same order, all definitions and
 theorems for which none of the signature functions is ancestral.  Now collect
 up all formulas (theorems) introduced in the @(tsee encapsulate) other than
 definitional axioms.  Add to this set any of those definitional equations that
 is either subversive or defines a function used in a formula in the set.  The
 conjunction of the resulting set of formulas is called the ``constraint'' and
 the set of all the signature functions of the @('encapsulate') together with
 all function symbols defined in the @('encapsulate') and mentioned in the
 constraint is called the ``constrained functions.''  Assign the constraint to
 each of the constrained functions.  Move, to just after the @('encapsulate'),
 the definitions of all function symbols defined in the @('encapsulate') that
 have been omitted from the constraint.</p>

 <p>Implementation note.  In the implementation we do not actually move @(see
 events), but we create constraints that pretend that we did.</p>

 <p>Here is an example illustrating our constraint-assigning algorithm.  It
 builds on the preceding examples.</p>

 @({
  (encapsulate
   (((sig-fn *) => *))

   (defun before1 (x)
     (if (consp x)
         (before1 (cdr x))
       x))

   (local (defun sig-fn (x) (cons x x)))

   (defthm sig-fn-prop
     (consp (sig-fn x)))

   (defun during (x)
     (if (consp x)
         x
       (cons (car (sig-fn x))
             17)))

   (defun before2 (x)
     (before1 x))

   (defthm before2-prop
     (atom (before2 x)))

   (defthm during-prop
     (implies (and (atom x)
                   (before2 x))
              (equal (car (during x))
                     (car (sig-fn x)))))

   (defun after1 (x)
     (sig-fn x))

   (defchoose after2 (x) (u)
     (and (< u x) (during x)))
   )
 })

 <p>Only the functions @('sig-fn') and @('during') receive extra constraints.
 The functions @('before1') and @('before2') are viewed as moving in front of
 the @(tsee encapsulate), as is the theorem @('before2-prop').  The functions
 @('after1') and @('after2') are viewed as being moved past the @(tsee
 encapsulate).  The implementation reports the following.</p>

 @({
  In addition to SIG-FN, we export AFTER2, AFTER1, BEFORE2, DURING and
  BEFORE1.

  The following constraint is associated with both of the functions DURING and
  SIG-FN:

  (AND (EQUAL (DURING X)
              (IF (CONSP X)
                  X (CONS (CAR (SIG-FN X)) 17)))
       (CONSP (SIG-FN X))
       (IMPLIES (AND (ATOM X) (BEFORE2 X))
                (EQUAL (CAR (DURING X))
                       (CAR (SIG-FN X)))))
 })

 <p>Notice that the formula @('(consp (during x))') is not a conjunct of the
 constraint.  During the first pass of the @('encapsulate'), this formula is
 stored as a @(':')@(tsee type-prescription) rule deduced during the definition
 of the function @('during').  However, the rule is not exported because of a
 rather subtle soundness issue.  (If you are interested in details, see the
 comments in source function @('putprop-type-prescription-lst').)</p>

 <p>We conclude by asking (and to a certain extent, answering) the following
 question: Isn't there an approach to assigning constraints that avoids
 over-constraining more simply than our ``second cut'' above?  Perhaps it seems
 that given an @(tsee encapsulate), we should simply assign to each locally
 defined function the theorems exported about that function.  If we adopted
 that simple approach the events below would be admissible.</p>

 @({
  (encapsulate
   (((foo *) => *))
   (local (defun foo (x) x))
   (defun bar (x)
     (foo x))
   (defthm bar-prop
     (equal (bar x) x)
     :rule-classes nil))

  (defthm foo-id
    (equal (foo x) x)
    :hints (("Goal" :use bar-prop)))

  ; The following event is not admissible in ACL2.

  (defthm ouch!
    nil
    :rule-classes nil
    :hints
    (("Goal" :use
      ((:functional-instance foo-id
                             (foo (lambda (x) (cons x x))))))))
 })

 <p>Under the simple approach we have in mind, @('bar') is constrained to
 satisfy both its definition and @('bar-prop') because @('bar') mentions a
 function declared in the signature list of the encapsulation.  In fact,
 @('bar') is so-constrained in the ACL2 semantics of encapsulation and the
 first two events above (the @('encapsulate') and the consequence that @('foo')
 must be the identity function) are actually admissible.  But under the simple
 approach to assigning constraints, @('foo') is unconstrained because no
 theorem about it is exported.  Under that approach, @('ouch!') is provable
 because @('foo') can be instantiated in @('foo-id') to a function other than
 the identity function.</p>

 <p>It's tempting to think we can fix this by including definitions, not just
 theorems, in constraints.  But consider the following slightly more elaborate
 example.  The problem is that we need to include as a constraint on @('foo')
 not only the definition of @('bar'), which mentions @('foo') explicitly, but
 also @('abc'), which has @('foo') as an ancestor.</p>

 @({
  (encapsulate
   (((foo *) => *))
   (local (defun foo (x) x))
   (local (defthm foo-prop
            (equal (foo x) x)))
   (defun bar (x)
     (foo x))
   (defun abc (x)
     (bar x))
   (defthm abc-prop
     (equal (abc x) x)
     :rule-classes nil))

  (defthm foo-id
    (equal (foo x) x)
    :hints (("Goal" :use abc-prop)))

  ; The following event is not admissible in ACL2.

  (defthm ouch!
    nil
    :rule-classes nil
    :hints
    (("Goal" :use
      ((:functional-instance foo-id
                             (foo (lambda (x) (cons x x)))
                             (bar (lambda (x) (cons x x))))))))
 })")

(defxdoc constraint-info
  :parents (system-utilities constraint)
  :short "Obtaining the @(see constraint) on a function symbol"
  :long "<p>See @(see constraint)s for relevant background.
 @('Constraint-info') is a rather technical system utility, and detailed
 documentation may be found in comments in the ACL2 source code, in particular
 in the definition of @('constraint-info').  Here we give only an overview of
 this utility.</p>

 <p>For a function symbol, @('fn'), and a logical @(see world), @('wrld')
 &mdash; for example, the current world, @('(w state)') &mdash; evaluation of
 the form @('(constraint-info fn wrld)') returns @('(mv flg x origins)'), as
 follows.  When @('flg') is @('nil'), @('x') is a term and @('origins') is a
 single <i>origin token</i> such as @('(DEFUN FN)'), indicating the source of
 the constraint, @('x'), on @('fn').  When @('flg') is non-@('nil') it is a
 function name, and usually @('x') is a list of terms and @('origins') is an
 equally long list of corresponding origin tokens; but there is a special case
 if the constraints are unknown, as can be the case with use of @(tsee
 partial-encapsulate).</p>

 <p>We illustrate with the following example.</p>

 @({
 (encapsulate
   (((f1 *) => *)
    ((f3 *) => *))
   (local (defun f1 (x) x))
   (defun f2 (x) (f1 x))
   (local (defun f3 (x) x))
   (defun f4 (x) (f3 x))
   (defthm f1-prop (equal (f1 x) (f4 x))))
 })

 <p>Then we can see the results of @('constraint-info') on each introduced
 function symbol, as follows.</p>

 @({
 ACL2 !>(let ((wrld (w state)))
          (list
           'result
           'f1
           (mv-let (flg1 x1 origin1)
             (constraint-info 'f1 wrld)
             (list flg1 x1 origin1))
           'f2
           (mv-let (flg2 x2 origin2)
             (constraint-info 'f2 wrld)
             (list flg2 x2 origin2))
           'f3
           (mv-let (flg3 x3 origin3)
             (constraint-info 'f3 wrld)
             (list flg3 x3 origin3))
           'f4
           (mv-let (flg4 x4 origin4)
             (constraint-info 'f4 wrld)
             (list flg4 x4 origin4))))
 (RESULT F1
         (F1 ((EQUAL (F4 X) (F3 X))
              (EQUAL (F1 X) (F4 X)))
             ((DEFUN F4) (THEOREM F1-PROP)))
         F2
         (NIL (EQUAL (F2 X) (F1 X)) (DEFUN F2))
         F3
         (F1 ((EQUAL (F4 X) (F3 X))
              (EQUAL (F1 X) (F4 X)))
             ((DEFUN F4) (THEOREM F1-PROP)))
         F4
         (F1 ((EQUAL (F4 X) (F3 X))
              (EQUAL (F1 X) (F4 X)))
             ((DEFUN F4) (THEOREM F1-PROP))))
 ACL2 !>
 })

 <p>Notice that the flag (first result) for @('f2') is @('nil'), because even
 though the definition of @('f2') is lexically inside the @('encapsulate'), it
 doesn't affect the constraints because it can be safely moved to just after
 the @('encapsulate').  However, the definition of @('f4') does affect (or
 ``infect''; see @(see subversive-recursions)) the constraints: it can't be
 moved to after the @('encapsulate') because of the @('defthm') after it.</p>")

(defxdoc constraint-tracking
  :parents (encapsulate)
  :short "Generate markers to indicate origins of constraints"
  :long "See @(tsee set-constraint-tracking).")

(defxdoc context-message-pair
  :parents (kestrel-utilities system-utilities-non-built-in)
  :short "A common ACL2 programming idiom: @(see error-triple)s without @(see
 state)"
  :long "<p><i>Context-message pairs</i> are of the form @('(mv erp val)'),
 where there are the following two cases: the first indicates a successful
 computation and the second indicates an error.</p>

 <ul>

 <li><b>Normal case</b>: @('erp') is @('nil') and @('val') is what we call the
 ``value'' of that context-message pair.</li>

 <li><b>Error case</b>: @('erp') is not @('nil').  @('Val') may be @('nil');
 otherwise @('val') is a message (see @(see msgp)) suitable for printing with
 @(tsee fmt) and related functions using the @('~@') directive, and @('erp') is
 a context suitable for error messages (see @(see ctx)).  A convention
 generally observed (for example, by ACL2 system function
 @('cmp-to-error-triple'), which converts a context-message pair to an @(see
 error-triple) that may be printed in the error case) is when @('erp') and
 @('val') are both non-@('nil'), then @('erp') is not @('t').</li>

 </ul>

 <p>To see how this works let us consider the ACL2 source function,
 @('translate-cmp'), whose input is a user-level (``untranslated'') term as
 input and returns a context-message pair.  In the non-error case, the value
 returned is the internal (``translated'') form of that input; see @(see term).
 The log below first shows a successful translation, returning multiple values
 @('(mv nil (binary-+ x '3))'), thus illustrating the ``Normal case'' above,
 where the first value returned (the error indicator) is @('nil') and the
 second is the value of the pair.  The second example in the log shows an error
 case returning a context and a message.  Don't worry about the various
 arguments of @('translate-cmp'); the examples are merely to illustrate
 programming with context-message pairs, not to explain @('translate-cmp')!</p>

 @({
 ACL2 !>(translate-cmp '(+ x 3)
                       t t t 'top (w state)
                       (default-state-vars state))
 (NIL (BINARY-+ X '3))
 ACL2 !>(translate-cmp '(quote 3 4)
                       t t t 'top (w state)
                       (default-state-vars state))
 (TOP ("The proper form of a quoted constant is (quote x), but ~
                      ~x0 is not of this form."
           (#0 QUOTE 3 4)))
 ACL2 !>
 })

 <p>The following macros are useful when programming with context-message
 pairs.</p>

 <ul>

 <li>@('(value-cmp x)'): same as @('(mv nil x)').  Example:
 @({
 ACL2 !>(value-cmp (* 3 4))
 (NIL 12)
 ACL2 !>
 })</li>

 <li>@('(er-cmp ctx str &rest args)'): Return @('(mv ctx msg)') where @('msg')
 is formed from @('str') and @('args').  Example:
 @({
 ACL2 !>(er-cmp 'example
                "I don't like 3-element lists like ~x0.~|"
                (make-list 3))
 (EXAMPLE ("I don't like 3-element lists like ~x0.~|" (#0 NIL NIL NIL)))
 ACL2 !>(mv-let (ctx msg)
          (er-cmp 'example
                  "I don't like 3-element lists like ~x0.~|"
                  (make-list 3))
          (fmx "Error in ~x0: ~@1" ctx msg))
 Error in EXAMPLE: I don't like 3-element lists like (NIL NIL NIL).
 (0 <state>)
 ACL2 !>
 })</li>

 <li>@('(er-let*-cmp alist body)'): Analogue of @(tsee er-let*) for
 context-message pairs.  So, it evaluates the bindings in @('alist') much as
 @(tsee let*)-bindings would be evaluated, but where each expression should
 return a context-message pair and so should @('body').  If any of those
 expression evaluations returns a pair with a non-nil first value, then that
 pair is returned.  Otherwise, @('body') &mdash; which should return a
 context-message pair &mdash; is evaluated with respect to the resulting
 bindings.  Examples (refer to previous examples that use @('translate-cmp')):

 @({
 ACL2 !>(er-let*-cmp ((x (value-cmp '(+ x 3)))
                      (val (translate-cmp x
                                          t t t 'top (w state)
                                          (default-state-vars state)))
                      (y (value-cmp (list :term val))))
                     (value-cmp (list :result y)))
 (NIL (:RESULT (:TERM (BINARY-+ X '3))))
 ACL2 !>(er-let*-cmp ((x (value-cmp '(quote 3 4)))
                      (val (translate-cmp x
                                          t t t 'top (w state)
                                          (default-state-vars state)))
                      (y (value-cmp (list :term val))))
                     (value-cmp (list :result y)))
 (TOP ("The proper form of a quoted constant is (quote x), but ~
                      ~x0 is not of this form."
           (#0 QUOTE 3 4)))
 ACL2 !>
 })</li>

 <li>@('(er-progn-cmp form1 ... formk)'): Each @('formi') should evaluate to a
 context-message pair.  If any of these evaluations produces a pair with a
 non-@('nil') first component (thus indicating an error), return that pair.
 Otherwise return the context-message pair produced by evaluating @('formk').
 Examples:

 @({
 ACL2 !>(er-progn-cmp (value-cmp (+ 2 8))
                      (er-cmp 'top "Ouch")
                      (value-cmp (* 3 4)))
 (TOP ("Ouch"))
 ACL2 !>(er-progn-cmp (value-cmp (+ 2 8))
                      (value-cmp (* 3 4)))
 (NIL 12)
 ACL2 !>
 })</li>

 </ul>")

(defxdoc copyright
  :parents (about-acl2)
  :short "ACL2 copyright, license, authorship"
  :long "<p>This topic provides information about copyright, license, and
 authorship of the ACL2 system.  For information about copyright and authorship
 of @(see documentation), see @(see documentation-copyright), which notes that
 there are many documentation authors.</p>

 <p>@(`(:raw (@ acl2-version))`) &mdash; A Computational Logic for Applicative
 Common Lisp</p>

 <p>Copyright (C) 2026, Regents of the University of Texas</p>

 <p>This version of ACL2 is a descendant of ACL2 Version 1.9, Copyright (C)
 1997 Computational Logic, Inc.  See the documentation topic NOTE-2-0.</p>

 <p>This program is free software; you can redistribute it and/or modify it
 under the terms of the LICENSE file distributed with ACL2.</p>

 <p>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 LICENSE for more details.</p>

 <p>Written by: Matt Kaufmann and J Strother Moore<br/>
 email: Kaufmann@@cs.utexas.edu and Moore@@cs.utexas.edu<br/>
 Department of Computer Science<br/>
 University of Texas at Austin<br/>
 Austin, TX 78712 U.S.A.</p>

 <p>Please also see @(see acknowledgments).</p>")

(defxdoc corollary
  :parents (rule-classes)
  :short "The corollary formula of a @(see rune)"
  :long "<p>See @(see formula).  This is a low-level system function at the
 present time.  See @(see pr) and see @(see pr!) instead.  Also see @(see
 rule-classes) for the use of the symbol @(':corollary') in specifying a rule
 class.</p>")

(defxdoc count
  :parents (lists strings acl2-built-ins)
  :short "Count the number of occurrences of an item in a string or true-list"
  :long "@({
  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)
 })

 <p>@('(Count item sequence)') returns the number of times @('item') occurs in
 @('sequence').  The @(see 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.</p>

 <p>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.</p>

 @(def count)")

(defxdoc count-keys
  :parents (stobj acl2-built-ins)
  :short "Count the number of keys in association list"
  :long "<p>@('(Count-keys al)') returns the number of distinct keys in an
 association list.</p>

 <p>@('Count-keys') has a guard of @('t').  This function is called in the body
 of function, @('<h>-count') where @('<h>') is a hash-table field of a @(see
 stobj).  See @(see defstobj).</p>

 @(def hons-remove-assoc)

 @(def count-keys)")

(defxdoc course-materials
  :parents (documentation)
  :short "Some ACL2 course materials"
  :long "<p>The links listed below will take you to materials for some courses
that involve ACL2.  This list is loosely maintained and incomplete, and is
given in no particular order.  We strongly encourage you to send email to <a
href='mailto:kaufmann@cs.utexas.edu'>Matt Kaufmann</a> and <a
href='mailto:moore@cs.utexas.edu'>J Strother Moore</a> if you have additional
such links to contribute; or if you are a contributor to the ACL2 @(see
community-books), please feel free to add them yourself.</p>

<ul>

<li>See @(see recursion-and-induction) for notes you can use to teach yourself
how to prove theorems about recursively defined functions using mathematical
induction.  That document started as notes for the course &ldquo;Recursion and
Induction&rdquo; in the Department of Computer Science of the University of
Texas at Austin.</li>

<li><a href='https://www.ccs.neu.edu/home/pete/teaching.html'>Courses
    taught by Pete Manolios</a>, which use
    the <see topic='@(url acl2-sedan)'>ACL2 Sedan
    (ACL2s)</see>,
    including <a href='https://www.ccs.neu.edu/home/pete/courses/Logic-and-Computation/2020-Spring/'>one
    taught at Northeastern in Spring 2020</a></li>

<li>The following two interfaces to ACL2 support the teaching of ACL2
to undergraduates:

  <ul>

  <li>The <see topic='@(url acl2-sedan)'>ACL2 Sedan (ACL2s)</see></li>

  <li><a href='http://dracula-lang.github.io/index.html'>DrACuLa</a></li>

  </ul></li>

<li>John Cowles, <a href='http://www.cs.uwyo.edu/~cowles/jvm-acl2/'>COSC5010:
Formalizing the JVM in ACL2</a>, Univ. of Wyoming</li>

<li>Links to some of Warren Hunt's courses, many of which use ACL2, may be found <a
href='http://www.cs.utexas.edu/users/hunt/class/index.html'>here</a>.</li>

<li>Links to some of J Moore's courses, many of which use ACL2, may be found <a
href='http://www.cs.utexas.edu/users/moore/classes/index.html'>here</a>.</li>

</ul>

")

(defxdoc cpu-core-count
  :parents (parallelism acl2-built-ins)
  :short "The number of cpu cores"
  :long "<p>This @(see documentation) topic relates to the experimental
 extension of ACL2 supporting parallel execution and proof; see @(see
 parallelism).</p>

 <p>Unless the ACL2 executable supports parallel execution (see @(see
 parallelism)), this function returns @('(mv 1 state)').  Otherwise:</p>

 <p>@('(Cpu-core-count state)') returns @('(mv core-count state)'), where
 @('core-count') is determined as follows.  If environment variable
 @('ACL2_CORE_COUNT') has a non-empty value, then that value should represent a
 positive integer (else an error occurs), which is the returned
 @('core-count').  Otherwise, the returned @('core-count') may be obtained from
 the underlying Common Lisp implementation, else as a positive integer value
 from @(see state) global variable @(''cpu-core-count') (see @(see assign)).
 Otherwise an error occurs.</p>

 @({
  Example:
  (cpu-core-count state) ==> (mv 4 state)
 })

 <p>@('Cpu-core-count') has the following logical definition.</p>

 @(def cpu-core-count)")

(defxdoc creating-executable
  :parents (installation-support)
  :short "Creating or obtaining an executable image"
  :long "<p>This topic may be avoided by following the @(see
  installation-instructions), which are intended to be
  self-contained.</p>

 <p>After obtaining the ACL2 sources, the next step is to produce an executable
 image.  Proceed according to one of the four sections below, and after reading
 that section, continue by reading the topic, see @(see using-acl2).</p>

 <ul>

 <li>Pre-built images</li>

 <li>Building an executable image on a Unix-like system</li>

 <li>Building an executable image on other than a Unix-like system</li>

 <li>Observations on building an executable image on a Windows system</li>

 </ul>

 <h3>Pre-built images</h3>

 <p>@(`(:raw (acl2-url-ref "distrib/images/Readme.html" "This website"))`)
 contains links to ACL2 executables and packages.  Each @('-md5sum') file was
 created using @('md5sum').  We may add additional links from time to time.</p>

 <p>See also @(see pre-built-binary-distributions).</p>

 <h3>Building an executable image on a Unix-like system</h3>

 <p>We assume you have obtained ACL2, described in
 @(see installation-instructions),
 but you have not obtained a pre-built image.  Change to the directory containing
 the ACL2 sources and execute the command</p>

 @({
 make LISP=<your_lisp>
 })

 <p>where @('<your_lisp>') is the command to run your local Common Lisp.
 By default, if no @('LISP=<your_lisp>') is specified, then @('LISP=ccl') is
 used, which presumably invokes CCL (see @(see obtaining-common-lisp)).</p>

 <p>This will create executable @('saved_acl2') in the current directory.</p>

 <p>The time taken to carry out this process depends on the host Lisp and the
 host processor but may well be under a minute.  The size of the resulting
 binary image is dependent on which Lisp was used, but it may be on the order
 of a couple hundred megabytes or so.</p>

 <p>This @('make') command works for the supported host Common Lisp
 implementations; see @(see obtaining-common-lisp), on systems we have
 tested.  If this @('make') command does not work for you, see the instructions
 below for &ldquo;Building an executable image on other than a Unix-like
 system&rdquo;.</p>

 <p>See @(see save-exec) for how to build an ACL2 executable from a state
 resulting from the running of specified @(see command)s.</p>

 <h3>Building an executable image on other than a Unix-like system</h3>

 <p>It may be best to use this option only if you are using a Common Lisp on
 which you cannot save an image (e.g., a trial version of a commercial
 lisp).</p>

 <p>Next we describe how to create a binary image containing ACL2 without using
 the `@('make')' utility.  If you cannot save an image, perhaps because you are
 using a trial version of your Common Lisp, then you may not be able to save an
 image.  In that case, see @(see running-acl2-without-executable).</p>

 <p>Your Common Lisp should be one of those listed in @(see
 obtaining-common-lisp).  Stand in the directory where you have downloaded
 ACL2.</p>

 <ol>

 <li>Remove file @('nsaved_acl2') if it exists.</li>

 <li>Start up Common Lisp and submit the following sequence of commands.

 @({
 (load "init.lisp")
 (in-package "ACL2")
 (compile-acl2) ; essentially a no-op if the Lisp is CCL or SBCL
 })

 The commands above may, depending on the host Lisp, compile the ACL2 sources
 and create compiled object files in the current directory.  (But they should
 be run even for Lisps that do not compile the ACL2 sources.)  Below, we assume
 that saved images have extension @('.core'); but this will depend on your host
 Lisp and operating system.</li>

 <li>Now exit your Common Lisp.  Make sure you are in the directory where you
 ran the commands displayed above.  Start your Common Lisp and run the
 following commands to <i>initialize</i> ACL2.

 @({
 (load "init.lisp")
 (in-package "ACL2")
 (save-acl2 (quote (initialize-acl2)) "saved_acl2")
 })

 This will load ACL2 source files (possibly compiled) into Lisp and then
 bootstrap ACL2 by reading and processing the source files, concluding by
 saving an image.  Exit Lisp now.  Subsequent steps will put the image in the
 right place.</li>

 <li>Remove @('osaved_acl2') if it exists.</li>

 <li><b>IF</b> @('saved_acl2') and @('saved_acl2.core') both exist <b>THEN</b>:
 <ul>
      <li>move @('saved_acl2.core') to @('osaved_acl2.core')</li>
      <li>move @('saved_acl2') to @('osaved_acl2')
          and edit @('osaved_acl2'), changing @('saved_acl2.core')
          (at end of line) to @('osaved_acl2.core')</li>
 </ul>
      <b>ELSE IF</b> @('saved_acl2') exists <b>THEN</b>:
 <ul>
      <li>move @('saved_acl2') to @('osaved_acl2')</li>
 </ul>
 </li>

 <li>Move @('nsaved_acl2') to @('saved_acl2') .</li>

 <li>Move @('nsaved_acl2.core') to @('saved_acl2.core') .</li>

 <li>Make sure @('saved_acl2') is executable.  For Windows
 this involves two mini-steps:

 <ul>

 <li>Remove the @('"$@"') from the @('saved_acl2') script (because Windows
 may not understand @('"$@"')).  Consequently, any arguments you pass to ACL2
 via the command line will be ignored.</li>

 <li>Rename @('saved_acl2') to @('saved_acl2.bat'), for
 example by executing the following command.
 @({
 rename saved_acl2 saved_acl2.bat
 })</li>

 </ul>
 </li>
 </ol>

 <h3>Observations on building an executable image on a Windows system</h3>

 <p>You may be able to avoid this section by downloading a pre-built binary
 distribution; see @(see pre-built-binary-distributions), and also see
 &ldquo;Pre-built images&rdquo; above.</p>

 <p>Otherwise, see @(see windows-installation) for information on installing
 ACL2 on Windows systems.</p>")

(defxdoc ctx
  :parents (errors)
  :short "Context object for error messages"
  :long "<p>Calls of @(tsee er), such as @('(er soft ctx ...)'), take a context
 argument, typically called @('ctx'), for the initial part of the message:
 @('"ACL2 Error in"').  If @('ctx') is @('nil'), only @('"ACL2 Error:"') is
 printed for that initial part of the message.  Otherwise, the string printed
 after @('"in"') depends on the form of that context, as follows.  (See @(see
 ctxp) for the definition of a valid context.)</p>

 <ul>

 <li>If @('ctx') is a symbol, print it with @(tsee fmt) using @('"~x"').</li>

 <li>If @('ctx') is a pair whose @('car') is a symbol, use @(tsee fmt) to print
 @('"(~x0 ~x1 ...)"'), with @('#\0') and @('#\1') bound respectively to the
 @('car') and @('cdr') of @('ctx').  <b>Exception</b>: if the @('car') is a
 member of the value of constant @('*fmt-ctx-spacers*'), then a space is
 printed after the left parenthesis.  That explains why there is a space, for
 example, in @('"( DEFUN"') in error messages starting with:

 @({
 ACL2 Error in ( DEFUN FOO ...):
 })</li>

 <li>Otherwise, print @('ctx') with @('fmt') using @('"~@"').</li>

 </ul>")

(defxdoc ctxp
  :parents (errors)
  :short "Recognizer for context objects for error messages"
  :long "<p>See @(see ctx) for relevant background.  The function @('ctxp')
  returns @('t') when @('ctx') is a valid context according to the definition
  below (also see @(see msgp)), else @('nil').</p>

 @(def ctxp)")

(defxdoc current-package
  :parents (ld)
  :short "The package used for reading and printing"
  :long "<p>@('Current-package') is an @(tsee ld) special (see @(see ld)).  The
 accessor is @('(current-package state)') and the updater is
 @('(set-current-package val state)'), or more conventionally, @('(in-package
 val)').  The value of @('current-package') is actually the string that names
 the package.  (Common Lisp's ``package'' objects do not exist in ACL2.)  The
 current package must be known to ACL2, i.e., it must be one of the initial
 packages or a package defined with @(tsee defpkg) by the user.</p>

 <p>When printing symbols, the package prefix is displayed if it is not the
 @('current-package') and may be optionally displayed otherwise.  Thus, if
 @('current-package') is @('"ACL2"') then the symbol @(''ACL2::SYMB') may be
 printed as @('SYMB') or @('ACL2::SYMB'), while @(''MY-PKG::SYMB') must be
 printed as @('MY-PKG::SYMB').  But if @('current-package') is @('"MY-PKG"')
 then the former symbol must be printed as @('ACL2::SYMB') while the latter may
 be printed as @('SYMB').</p>

 <p>In Common Lisp, @('current-package') also affects how objects are read from
 character streams.  Roughly speaking, read and print are inverses if the
 @('current-package') is fixed, so reading from a stream produced by printing
 an object must produce an equal object.</p>

 <p>In ACL2, the situation is more complicated because we never read objects
 from character streams, we only read them from object ``streams'' (channels).
 Logically speaking, the objects in such a channel are fixed regardless of the
 setting of @('current-package').  However, our host file systems do not
 support the idea of Lisp object files and instead only support character
 files.  So when you open an object input channel to a given (character file)
 we must somehow convert it to a list of ACL2 objects.  This is done by a
 <i>deus ex machina</i> (``a person or thing that appears or is introduced
 suddenly and unexpectedly and provides a contrived solution to an apparently
 insoluble difficulty,'' Webster's Ninth New Collegiate Dictionary).  Roughly
 speaking, the <i>deus ex machina</i> determines what sequence of calls to
 @('read-object') will occur in the future and what the @('current-package')
 will be during each of those calls, and then produces a channel containing the
 sequence of objects produced by an analogous sequence of Common Lisp reads
 with @('*current-package*') bound appropriately for each.</p>

 <p>A simple rule suffices to make sane file @(see io) possible: before you
 read an object from an object channel to a file created by printing to a
 character channel, make sure the @('current-package') at read-time is the same
 as it was at print-time.</p>")

(defxdoc current-theory
  :parents (theories theory-functions)
  :short "Currently @(see enable)d rules as of logical name"
  :long "@({
  Examples:
  (current-theory :here)
  (current-theory 'lemma3)
 })

 <p>See @(see logical-name).</p>

 @({
  General Form:
  (current-theory logical-name)
 })

 <p>Returns the current theory as it existed immediately after the introduction
 of @(tsee logical-name) provided it is evaluated in an environment in which
 the variable symbol WORLD is bound to the current ACL2 logical world, @('(w
 state)').  Thus,</p>

 @({
  ACL2 !>(current-theory :here)
 })

 <p>will cause an (unbound variable) error while</p>

 @({
  ACL2 !>(let ((world (w state))) (current-theory :here))
 })

 <p>will return the current theory in world.</p>

 <p>See @(see theories) and see @(see logical-name) for a discussion of
 theories in general and why the commonly used ``theory functions'' such as
 @('current-theory') are really macros that expand into terms involving the
 variable @('world').</p>

 <p>The theory returned by @('current-theory') is in fact the theory selected
 by the @(tsee in-theory) event most recently preceding logical name, extended
 by the rules introduced up through @(tsee logical-name).</p>

 <p>You may experience a fencepost problem in deciding which logical name to
 use.  @(tsee Deflabel) can always be used to mark unambiguously for future
 reference a particular point in the development of your theory.  The order of
 @(see events) in the vicinity of an @(tsee encapsulate) is confusing.  See
 @(see encapsulate).</p>

 <p>This ``function'' is actually a macro that expands to a term mentioning the
 single free variable @(tsee world).  When theory expressions are evaluated by
 @(tsee in-theory) or the @(':')@(tsee in-theory) hint, @(tsee world) is bound
 to the current ACL2 @(see world).</p>")

(defxdoc custom-keyword-hints
  :parents (hints)
  :short "User-defined hints"
  :long "<p>See @(see add-custom-keyword-hint) for a discussion of how advanced
 users can define their own hint keywords.  For examples, see the community
 books directory @('books/hints/'), in particular @('basic-tests.lisp').</p>")

(defxdoc cw
  :parents (io acl2-built-ins)
  :short "Print to the comment window"
  :long "<p>@('Cw') is a macro that expands to a function whose guard is
 @('t').  For a guarded variant of @('cw'), see @(see fmx-cw).  For variants of
 @('cw') that provide readable output (suffix @('"!"')) and are never
 inhibited (suffix @('"+"')), see @(see cw!), @(see cw+), and @(see cw!+).
 For corresponding functions see @(see fmt-to-comment-window), @(see
 fmt-to-comment-window!), @(see fmt-to-comment-window+), and @(see
 fmt-to-comment-window!+).</p>

 <p>Example:</p>

 @({
  (cw "The goal is ~x0 and the alist is ~x1.~%"
      (untranslate term t nil)
      unify-subst)
 })

 <p>Logically, this expression is equivalent to @('nil').  However, it has the
 effect of first printing to the so-called ``comment window'' the @(tsee fmt)
 string as indicated.  Thus, @('cw') is like @('fmt') (see @(see fmt)) except
 in four important ways.  First, it is a macro whose calls expand to calls of
 a @(':')@(tsee logic) mode function.  Second, it neither takes nor returns the
 ACL2 @(tsee state); logically @('cw') simply returns @('nil'), although it
 prints to a <i>comment window</i> that just happens to share the terminal
 screen with the standard character output @(tsee *standard-co*).  Third, its
 @('fmt') args are positional references, so that for example</p>

 @({
  (cw "Answers: ~x0 and ~x1" ans1 ans2)
 })

 <p>prints in the same manner as:</p>

 @({
  (fmt "Answers: ~x0 and ~x1"
       (list (cons #\0 ans1) (cons #\1 ans2))
       *standard-co* state nil)
 })

 <p>And finally, output from @('cw') is suppressed if the @('COMMENT') type of
 output is suppressed; see @(see set-inhibit-output-lst).</p>

 <p>Typically, calls of @('cw') are embedded in @(tsee prog2$) forms, e.g.,</p>

 @({
  (prog2$ (cw ...)
          (mv a b c))
 })

 <p>which has the side-effect of printing to the comment window and logically
 returning @('(mv a b c)').</p>

 @({
  General Form:
  (cw fmt-string arg1 arg2 ... argn)
 })

 <p>where n is between 0 and 9 (inclusive).  The macro uses @(tsee
 fmt-to-comment-window), passing it the column @('0') and @(see evisc-tuple)
 @('nil'), after assembling the appropriate alist binding the @(tsee fmt) vars
 #\0 through #\9; see @(see fmt).  If you want</p>

 @({
  (a) more than 10 vars,
  (b) vars other than the digit chars,
  (c) a different column, or
  (d) a different evisc-tuple,
 })

 <p>then call @(tsee fmt-to-comment-window) instead.</p>

 <p>Finally, we discuss another way to create formatted output that also avoids
 the need to pass in the ACL2 @(tsee state).  The idea is to use wormholes; see
 @(see wormhole).  Below is a function you can write, along with some calls,
 providing an illustration of this approach.</p>

 @({
  (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))))
 })")

(defxdoc cw!
  :parents (cw io acl2-built-ins)
  :short "Print readably to the comment window"
  :long "<p>See @(see cw) for important background.</p>

 <p>This is nearly the same as @(tsee cw), but @('cw!') avoids
 inserting backslash (\) characters when forced to print past the right
 margin.  Use @('cw!') if you want to be able to read the forms back in.</p>")

(defxdoc cw+
  :parents (cw io acl2-built-ins)
  :short "Print uninhibited to the comment window"
  :long "<p>See @(see cw) for important background.</p>

 <p>This is nearly the same as @(tsee cw), but @('cw+') always produces output,
 even when the @('COMMENT') output type is inhibited (see @(see
 set-inhibit-output-lst)).</p>")

(defxdoc cw!+
  :parents (cw io acl2-built-ins)
  :short "Print readably and uninhibited to the comment window"
  :long "<p>See @(see cw) for important background.</p>

 <p>This is nearly the same as @(tsee cw), but @('cw+') always produces
 readable output (like @(tsee cw!)), even when the @('COMMENT') output type is
 inhibited (like @(tsee cw+)).</p>")

(defxdoc cw-gstack
  :parents (break-rewrite debugging)
  :short "Debug a rewriting loop or stack overflow"
  :long "<p>After @(see break-rewrite) is enabled (with @(':')@(tsee brr)@('
 t') or in the scope of @(tsee with-brr-data)), @('cw-gstack') can be invoked
 to show a stack backtrace when a proof is interrupted (because of control-c or
 because of a loop).</p>

 @({
  Example Forms:
  (cw-gstack)
  (cw-gstack :frames 10)       ; show only the top 10 frames
  (cw-gstack :frames '(1 10))  ; same as above:  show only frames 1 through 10
  (cw-gstack :frames '(10 20)) ; show only frames 10 through 20
  (cw-gstack :evisc-tuple (evisc-tuple 3 4 nil nil))
                               ; print with print-level 3 and print-length 4
  (cw-gstack :evisc-tuple nil) ; print using default ``evisceration'',
                               ;   essentially the same as just above
  (cw-gstack :evisc-tuple '(nil 3 4 (hide)))
                               ; same as just above

  General Form:
  (cw-gstack :frames frames :evisc-tuple evisc-tuple)
 })

 <p>where @(':frames') and @(':evisc-tuple') are optional, but if they are
 supplied, their values are evaluated.  The value of @('frames') should be
 either a natural number or a list of two natural numbers, the first less than
 the second; and the value of @('evisc-tuple') should be an evisc-tuple (see
 @(see evisc-tuple)).  If @(':evisc-tuple') is omitted, then by default,
 substructures deeper than 3 are replaced by ``@('#')'' and those longer than 4
 are replaced by ``@('...')'', and terms of the form @('(hide ...)') are
 printed as @('<hidden>'); this behavior can be changed by setting the
 @(':TERM') @(see evisc-tuple) (see @(see set-evisc-tuple)).  Also see @(see
 set-iprint) for an alternative to printing ``@('#')'' and ``@('...')''.</p>

 <p>Stack overflows may occur, perhaps caused by looping rewrite rules.  In
 some Lisps, stack overflows may manifest themselves as segmentation faults,
 causing the entire ACL2 image to crash.  Finding looping rewrite rules can be
 tricky, especially if you are using books supplied by other people.  (However,
 see @(see set-rewrite-stack-limit) for a way to avoid stack overflows caused
 by rewriter loops.)</p>

 <p>Normally, a stack overflow will cause the printing of an error message that
 suggests how to proceed.  Just follow those instructions, and you will
 generally be able to see what is causing the loop.</p>

 <p>Suggestion: Once you have found the loop and fixed it, you should execute
 the ACL2 command @(':')@(tsee brr)@(' nil'), so that you don't slow down
 subsequent proof attempts.</p>")

(defxdoc cw-print-base-radix
  :parents (io acl2-built-ins)
  :short "Print to the comment window in a given print-base"
  :long "<p>See @(tsee cw) for relevant background.  This variant of @('cw')
 requires specification of a print-base and, optionally, a print-radix (see
 @(see set-print-base), @(see set-print-radix), and @(see
 set-print-base-radix)).</p>

 <p>The following examples show that @('cw-print-base-radix') is just like
 @(tsee cw), except that there is a new argument in the first position that
 specifies the print-base and can, for that print-base, override the default
 print-radix.</p>

 @({
 ACL2 !>(cw-print-base-radix 16 "~x0~%" '(3 12 16 17))
 (#x3 #xC #x10 #x11)
 NIL
 ACL2 !>(cw-print-base-radix '(16 . t) "~x0~%" '(3 12 16 17))
 (#x3 #xC #x10 #x11)
 NIL
 ACL2 !>(cw-print-base-radix '(16 . nil) "~x0~%" '(3 12 16 17))
 (3 C 10 11)
 NIL
 ACL2 !>(cw-print-base-radix 10 "~x0~%" '(3 12 16 17))
 (3 12 16 17)
 NIL
 ACL2 !>(cw-print-base-radix '(10 . t) "~x0~%" '(3 12 16 17))
 (3. 12. 16. 17.)
 NIL
 ACL2 !>(cw-print-base-radix '(10 . nil) "~x0~%" '(3 12 16 17))
 (3 12 16 17)
 NIL
 ACL2 !>

 General Forms:

 (cw-print-base-radix print-base fmt-string arg1 arg2 ... argn)
 (cw-print-base-radix print-base/print-radix fmt-string arg1 arg2 ... argn)
 })

 <p>where all arguments of this macro are evaluated; @('print-base') is a legal
 print-base as recognized by @(tsee print-base-p); @('print-base/print-radix')
 is a cons whose car is a legal print-base; @('fmt-string') is a string
 suitable for passing to @(tsee fmt); and @('arg1') through @('argn') (where n
 is at most 9) are corresponding arguments for @('fmt-string').  Printing is
 done according to the specified print-base, which is the first argument in the
 first general form and is the car of the first argument in the second general
 form.  The print-radix value that is used for printing in the first general
 form is the print-radix as specified for @(tsee set-print-base-radix), while
 in the second general form, it is the cdr.</p>")

(defxdoc cw-print-base-radix!
  :parents (io acl2-built-ins)
  :short "Print to the comment window in a given print-base"
  :long "<p>This is nearly the same as @(tsee cw-print-base-radix), but
  @('cw-print-base-radix!') avoids inserting backslash (\) characters when
  forced to print past the right margin.  Use @('cw-print-base-radix!')  if you
  want to be able to read the forms back in.</p>")

(defxdoc |Common Lisp|
  :parents (|Pages Written Especially for the Tours|)
  :short "Common Lisp"
  :long "<p><see topic='@(url
 |An Example Common Lisp Function Definition|)'><img
 src='res/tours/walking.gif'></img></see></p>

 <p>The logic of ACL2 is based on Common Lisp.</p>

 <p>Common Lisp is the standard list processing programming language.  It is
 documented in: Guy L. Steele, <a
 href='https://www.cs.cmu.edu/Groups/AI/html/cltl/cltl2.html'><b>Common Lisp
 The Language</b></a>, Digital Press, 12 Crosby Drive, Bedford, MA 01730,
 1990.</p>

 <p>ACL2 formalizes only a subset of Common Lisp.  It includes such familiar
 Lisp functions as @('cons'), @('car') and @('cdr') for creating and
 manipulating list structures, various arithmetic primitives such as @('+'),
 @('*'), @('expt') and @('<='), and @('intern') and @('symbol-name') for
 creating and manipulating symbols.  Control primitives include @('cond'),
 @('case') and @('if'), as well as function call, including recursion.  New
 functions are defined with @('defun') and macros with @('defmacro').  See
 @(see programming) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> for a list of the Common Lisp primitives
 supported by ACL2.</p>

 <p>ACL2 supports five of Common Lisp's datatypes:</p>

 <p>* the precisely represented, unbounded numbers (integers, rationals, and
 the complex numbers with rational components, called the ``complex rationals''
 here),</p>

 <p>* the characters with ASCII codes between 0 and 255</p>

 <p>* strings of such characters</p>

 <p>* symbols (including packages)</p>

 <p>* conses</p>

 <p>ACL2 is a large subset of the first-order <b>applicative</b> part of Common
 Lisp.  (Roughly speaking, a language is applicative if it follows the rules of
 function application.  For example, @('f(x)') must be equal to @('f(x)'),
 which means, among other things, that the value of @('f') must not be affected
 by ``global variables'' and the object @('x') must not change over time.)  It
 does not support higher-order features of Common Lisp, like functional objects
 and <tt>apply</tt>.  It does not support Common Lisp primitives that have
 side-effects such as <tt>setq</tt>, <tt>setf</tt>, the Common Lisp Object
 System, etc.  However, ACL2 does provide some special features that can be
 used efficiently to do many of the same jobs as these omitted Common Lisp
 primitives.  The ACL2 system is largely implemented in the language it
 supports.</p>

 <p><see topic='@(url |An Example Common Lisp Function Definition|)'><img
 src='res/tours/walking.gif'></img></see></p>")

(defxdoc |Common Lisp as a Modeling Language|
  :parents (|Pages Written Especially for the Tours|)
  :short "Common Lisp as a Modeling Language"
  :long "<p>In ACL2 we have adopted Common Lisp as the basis of our modeling language.
 If you have already read our brief note on Common Lisp and recall the example
 of @('app'), please proceed.  Otherwise click <see topic='@(url
 |Common Lisp|)'>here</see> for an exceedingly brief introduction to Common
 Lisp and then come <b>back</b> here.</p>

 <p>In Common Lisp it is very easy to write systems of formulas that manipulate
 discrete, inductively constructed data objects.  In building a model you might
 need to formalize the notion of sequences and define such operations as
 concatenation, length, whether one is a permutation of the other, etc.  It is
 easy to do this in Common Lisp.  Furthermore, if you have a Common Lisp
 ``theory of sequences'' you can <b>run</b> the operations and relations you
 define.  That is, you can execute the functions on concrete data to see what
 results your formulas produce.</p>

 <p>If you define the function @('app') as shown above and then type</p>

 @({
  (app '(A B) '(C D E))
 })

 <p>in any Common Lisp, the answer will be computed and will be @('(A B C D
 E)').</p>

 <p>The <b>executable</b> nature of Common Lisp and thus of ACL2 is very handy
 when producing models.</p>

 <p>But executability is not enough for a modeling language because the purpose
 of models is to permit analysis.</p>

 <p>Click <see topic='@(url |Analyzing Common Lisp Models|)'>here</see> to
 continue.</p>")

(defxdoc |Corroborating Models|
  :parents (|Pages Written Especially for the Tours|)
  :short "Corroborating Models"
  :long "<p><see topic='@(url |Models of Computer Hardware and Software|)'><img
 src='res/tours/flying.gif'></img></see></p>

 <p>After producing a model, it must be <b>corroborated</b> against reality.
 The Falling Body Model has been corroborated by a vast number of experiments
 in which the time and distance were measured and compared according to the
 formula.  In general all models must be corroborated by experiment.</p>

 <p>The Falling Body Model can be derived from deeper models, namely Newton's
 laws of motion and the assertion that, over the limited distances concerned,
 gravitation exerts a constant acceleration on the object.  When the model in
 question can be derived from other models, it is the other models that are
 being corroborated by our experiments.</p>

 <p>Because nature is not formal, we cannot <b>prove</b> that our models of it
 are correct.  All we can do is test our models against nature's behavior.</p>

 <p>Such testing often exposes restrictions on the applicability of our models.
 For example, the Falling Body Model is inaccurate if air resistance is
 significant.  Thus, we learn not to use that model to predict how long it
 takes a feather to fall from a 200 foot tower in the earth's atmosphere.</p>

 <p>In addition, attempts at corroboration might reveal that the model is
 actually incorrect.  Careful measurements might expose the fact that the
 gravitational force increases as the body falls closer to earth.  Very careful
 measurements might reveal relativistic effects.  Technically, the familiar
 Falling Body Model is just wrong, even under excessive restrictions such as
 ``in a perfect vacuum'' and ``over small distances.''  But it is an incredibly
 useful model nonetheless.</p>

 <p>There are several morals here.</p>

 <p><b>Models need not be complete to be useful.</b></p>

 <p><b>Models need not be perfectly accurate to be useful.</b></p>

 <p><b>The user of a model must understand its limitations.</b></p>

 <p><see topic='@(url |Models of Computer Hardware and Software|)'><img
 src='res/tours/flying.gif'></img></see></p>")

(defxdoc dead-events
  :parents (debugging)
  :short "Using proof supporters to identify dead code and unused theorems"
  :long "<p>Below, when we talk about ``an event @('A')'', we mean an event
 whose name is @('A').</p>

 <p>When event @('A') is used in a proof performed to admit event @('B') that
 you submit to ACL2, we say that @('A') is a ``proof-supporter'' of @('B').
 ACL2 stores an association list such that for every event @('B') with at least
 one proof-supporter, @('B') is associated with a list of all of its
 proof-supporters, sorted by @(tsee symbol<).  The following form evaluates to
 that alist, which is called the ``proof-supporters-alist''.</p>

 @({
  (global-val 'proof-supporters-alist (w state))
 })

 <p>By ``used in a proof'' above, we mean: applied as a rule or supplied
 explicitly via @(see hints) of type @(':use'), @(':by'), or
 @(':clause-processor').  That is, the @(see events) ``used in a proof'' for
 admitting an event @('E') are those listed in the @(see summary) printed at
 the conclusion of admitting @('E').</p>

 <p>Note that if proofs are skipped when admitting event @('E'), say because
 the last admission of @('E') was done by @(tsee include-book) (or
 @('certify-book'), which ends with an @(tsee include-book)), then there will
 be no entry in that alist for @('E').  (An exception is made however for
 @(tsee encapsulate) @(see events), where proof-supporters are remembered from
 the first pass; see below.)  So if you want the proof-supporters-alist to
 include supporters for events in a book, use @(tsee ld) rather than @(tsee
 include-book) or @(tsee certify-book) to process the events in that book.  If
 however you are interested in the proof-supporters FROM a book that support a
 later event, then it is fine to include that book.</p>

 <p>The case for @(tsee encapsulate) is slightly tricky.  Consider an example
 of the following form.</p>

 @({
  A ; event preceding the encapsulate
  (encapsulate
   ()
   B
   (local C) ; uses A and B in a proof
   D ; uses C in a proof
   )
 })

 <p>At the conclusion of this @(tsee encapsulate) event, the
 proof-supporters-alist associates @('D') with @('A') and @('B'), but not
 @('C') (which has disappeared, since it is @(see local)).</p>

 <p>Note that this sort of ``transitive closure'' operation is only performed
 when necessary due to the disappearance of @(see local) @(see events).  For
 example, if we replace @('(local C)') above by just @('C'), then @('D') is
 associated in the proof-supporters-alist only with @('C'), not with @('A') or
 @('B').  If you want the transitive closure of the relation computed by the
 proof-supporters-alist, you have to compute it yourself. (This was a
 deliberate design decision, in order to avoid slowing down event processing.)
 However, there is help available on how to do such a computation:</p>

 <p>A community book, @('books/tools/dead-events.lisp'), does such a transitive
 closure, and moreover uses that information to find ``dead events'' relative
 to a list of ``desired'' events.  For example, suppose you use @(tsee LD) to
 process the events, with proofs, in a book intended to prove theorems
 @('MAIN-1') and @('MAIN-2').  (Remember, @(tsee certify-book) will not save
 such information.)  Suppose furthermore that the book begins with some @(tsee
 include-book) forms followed by @('(deflabel book-start)').  You could
 evaluate this form:</p>

 @({
  (dead-events '(main-1 main-2) :start 'book-start)
 })

 <p>The result is a list of events that you probably can delete from the book
 without causing any proofs to fail.  See the @('dead-events.lisp') book for
 further documentation.</p>

 <p>You might also find the code in the above book to be helpful for writing
 your own utilities based on the proof-supporters-alist.</p>")

(defxdoc dealing-with-key-combinations-of-function-symbols
  :parents (introduction-to-the-theorem-prover)
  :short "How to get rid of key combinations of function symbols"
  :long "<p>Suppose @('REV') reverses a list, @('MEMBER') checks that its first
 argument is an element of its second, and @('SQUARES-PLUS-3P') is some
 complicated predicate.  Suppose you're proving some Main Theorem that involves
 those concepts and the theorem prover presents you with the following hideous
 formula as a key checkpoint.  What action should you take?</p>

 <p>Hint: Don't read the formula ``for sense,'' i.e., don't try to understand
 what this formula is saying!  Just look at every subterm involving a nest of
 two function symbols and ask if you know something about those two symbols
 that allows you to <i>simplify</i> that one subterm.</p>

 @({
  (IMPLIES (AND (CONSP X)
                (MEMBER (+ 3 (* I I)) (REV X))
                (LIST-OF-INTEGERS X)
                (INTEGERP I)
                (<= 0 I)
                (INTEGERP K)
                (<= 0 K)
                (< I K)
                (SQUARES-PLUS-3P K X)
                (NOT (EQUAL (CAR X) (+ 3 (* I I))))
                (NOT (MEMBER (+ 3 (* I I)) X)))
           (SQUARES-PLUS-3P K (REV X)))?
 })

 <p>The experienced ACL2 user will stop reading at the second hypothesis!</p>

 @({
                (MEMBER (+ 3 (* I I)) (REV X))
 })

 <p>The combination of @('MEMBER') and @('REV') can be simplified.  The
 question ``is @('e') a member of @('(REV x)')'' can be answered by asking ``is
 @('e') a member of @('x')''.  The two questions are equivalent.  This insight
 comes from your intuition about the <i>semantics</i> of @('REV') &mdash; it
 just reorders the elements but doesn't add or delete any.  The second question
 is simpler since it doesn't mention @('REV'), so this is a good transformation
 to make.  And the theorem that they are equivalent is simpler than the key
 checkpoint above because it involves fewer functions and smaller
 expressions.</p>

 <p>You might formalize this insight as</p>

 @({
  (equal (member e (rev x))
         (member e x))
 })

 <p>But this conjecture is <i>not</i> a theorem, because @('(member e x)')
 returns the @('cdr') of @('x') that begins with @('e'), not just a Boolean
 (@('t') or @('nil')) indicating whether @('e') is an element of @('x').  The
 location of the first @('e') in @('(rev x)') is generally different than the
 location in @('x').  So when we say the two questions are ``equivalent'' we
 don't mean they are equal.  We mean that they're propositionally equivalent:
 both @('nil') or both non-@('nil').  This sense of equivalence is called ``if
 and only if'' and is checked by the function @('iff').</p>

 <p>So our intuitive insight can be phrased as this theorem:</p>

 @({
  (iff (member e (rev x))
       (member e x))
 })

 <p>Suggesting that this formulation of the insight is ``obvious'' begs many
 questions.  Mathematically, we could have avoided @('iff') and just written
 two implications:</p>

 @({
  (and (implies (member e x) (member e (rev x)))
       (implies (member e (rev x)) (member e x))).
 })

 <p>or</p>

 @({
  (and (implies (member e x) (member e (rev x)))
       (implies (not (member e x))  (not (member e (rev x))))).
 })

 <p>Or we could have used @('iff') but ``oriented'' it the other way:</p>

 @({
  (iff (member e x)
       (member e (rev x)))
 })

 <p>We choose to write</p>

 @({
  (iff (member e (rev x))
       (member e x))
 })

 <p>because of <i>our knowledge of how ACL2 turns formulas into rules!</i></p>

 <p>We deal with this at greater length later.  But just to drive the point
 home, if we issue the command:</p>

 @({
  (defthm member-rev
    (iff (member e (rev x))
         (member e x)))
 })

 <p>ACL2 will build in a rule that causes every propositional occurrence of
 @('(MEMBER e (REV x))') to be replaced by @('(MEMBER e x)').  (By
 ``propositional occurrence'' we mean an occurrence in which the value is
 tested, as by @('IF') or the propositional connectives.  Remember, one might
 use @('member') to determine the location of an element too.)</p>

 <p>Note carefully: <i>if you do not tell ACL2 how to make a rule</i> from a
 theorem, it makes a rewrite rule.  Rewrite rules always replace instances of
 the left-hand side by the corresponding instances of the right-hand side.
 That is, when interpreted as a rewrite rule, @('(iff ')<i>alpha</i>
 <i>beta</i>@(')') makes ACL2 replace <i>alpha</i> by <i>beta</i>.</p>

 <p>Probably the biggest mistake new users make is forgetting that every
 theorem they prove creates a very specific rule.  You must remember that you
 are <i>programming</i> ACL2 with these rules.  Being careless in your
 statement of theorems is tantamount to being careless in your programming.
 What you get is a mess.</p>

 <p>Had we proved the same equivalence, but with the @('iff') commuted, we
 would be giving ACL2 <i>bad advice</i>.  We would be telling it ``replace
 instances of @('(MEMBER e x)') by the corresponding instances of @('(MEMBER e
 (REV x))')''!  If ACL2 had that rule and ever tried to simplify any
 @('member') expression, e.g., @('(MEMBER A B)'), it would get into an infinite
 loop, e.g., producing the following sequence of transformations:</p>

 @({
  (MEMBER A B)
  (MEMBER A (REV B))
  (MEMBER A (REV (REV B)))
  ...
 })

 <p>until it eventually exhausted some resource.</p>

 <p>Recall that we entertained the idea of phrasing our insight about
 @('member') and @('rev') with implications rather than @('iff').  Generally
 speaking, implications produce weaker rules &mdash; rules that apply less
 often.  We discuss that later.</p>

 <p>Now suppose we've proved @('member-rev'), oriented so as to rewrite
 @('(member e (rev x))') to @('(member e x)'), and built it in as a rewrite
 rule.  Then suppose we repeated the attempt to prove our Main Theorem.  This
 time, when the prover is processing the hideous Key Checkpoint printed above,
 our new lemma, @('member-rev'), will hit it.  It will transform the formula
 to:</p>

 @({
  (IMPLIES (AND (CONSP X)
                (MEMBER (+ 3 (* I I)) X)   ; <-- the hyp has simplified
                (LIST-OF-INTEGERS X)
                (INTEGERP I)
                (<= 0 I)
                (INTEGERP K)
                (<= 0 K)
                (< I K)
                (SQUARES-PLUS-3P K X)
                (NOT (EQUAL (CAR X) (+ 3 (* I I))))
                (NOT (MEMBER (+ 3 (* I I)) X)))
           (SQUARES-PLUS-3P K (REV X)))?
 })

 <p>and then that will collapse to @('T'), since the @('IMPLIES') has
 contradictory hypotheses (note the last hypothesis above).</p>

 <p>By proving @('member-rev') we proved the hideous checkpoint.  We never had
 to look at the rest of the formula or think about why it is a theorem.
 Furthermore, attacking the main theorem again, from scratch, with
 @('member-rev') in the database, may eliminate other checkpoints that came up
 the last time we tried to prove our main goal.  So we recommend addressing one
 checkpoint at a time.</p>

 <p>This example illustrates that purely <i>local</i> thinking &mdash; looking
 for simplifiable combinations of function symbols &mdash; can sometimes lead
 to proofs and should always be your first reaction to a key checkpoint: what
 local fact do you know that would clean up the formula?  Don't think about
 deep questions like ``why is this true?'' until you can't see any way to make
 it simpler.</p>

 <p>It is important to train yourself to see combinations of function symbols
 and to create strong rules for eliminating them.  We will give you
 opportunities to practice this later in the tutorial.</p>

 <p>If you have been reading the tutorial introduction to the theorem prover,
 use your browser's <b>Back Button</b> now to return to @(see
 INTRODUCTION-TO-KEY-CHECKPOINTS).</p>")

(defxdoc dealing-with-tau-problems
  :parents (introduction-to-the-tau-system)
  :short "Some advice on dealing with problems caused by the tau system"
  :long "<p>For background on the tau system, see @(see
 introduction-to-the-tau-system).  The two most common problems caused by the
 tau system have to do with the system's interaction with ``legacy'' proof
 scripts.  Such scripts may suffer because they were not designed to exploit
 tau reasoning and which may configure the tau database in quite incomplete and
 arbitrary ways.  The two most common problems we have seen are (a) significant
 slow downs in a few proofs and (b) failed proof attempts due to hints being
 misapplied because the tau system caused subgoals to be renumbered.</p>

 <p>We discuss the rather limited means of dealing with these problems here.
 In @(see future-work-related-to-the-tau-system) we list some major
 inadequacies of the tau system.</p>

 <p>If the tau system contributes to a proof, the @(see rune) @('(:')@(tsee
 executable-counterpart)@(' tau-system)') will be listed among the Rules in the
 @(See Summary).  However, merely by being attempted the tau system can slow
 down proofs in which it makes no contribution.</p>

 <p>The most brutal and fool-proof way to isolate a proof from the tau system
 is to disable the entire system.  This can be done globally by</p>

 @({
  (in-theory (disable (tau-system)))  ; (:executable-counterpart tau-system)
 })

 <p>or locally with a subgoal specific hint:</p>

 @({
  ...
  :hints (("...subgoal id..." :in-theory (disable (tau-system))))
 })

 <p>Conducting a proof with and without the participation of the tau system can
 help you determine whether tau reasoning is helping or hurting.</p>

 <p><i>Dealing with Slowdowns</i></p>

 <p>The @(tsee time-tracker) utility was added to allow users to investigate
 whether excessive amounts of time are being spent in a given function.  It was
 then used to annotate the code for the tau system as described in @(see
 time-tracker-tau).  The result is that if ``excessive'' time is spent in tau
 reasoning, messages to that effect will be printed to the proof log.  The
 question is: aside from disabling the tau system how can the proof be sped
 up?</p>

 <p>There are two common causes of slowdown in the tau system.  The first stems
 from the system's use of @(':')@(tsee executable-counterpart)s to determine
 whether a constant has a given tau.  Recall that a tau is a conjunction of
 monadic predicates.  To determine whether some constant satisfies the tau, the
 predicates are executed.  If you have a hard-to-compute predicate this can be
 very slow.  The most typical such predicates in ACL2 applications are those
 that check invariants, e.g., that recognize ``good states'' or ``well-formed
 data.''  These are often written inefficiently because they are intended only
 for use in theorems and, before the tau system was added, they may have never
 been applied to constants.  The most common constants tau predicates are
 applied to are @('0'), @('T'), and @('NIL'), although different models may
 stress other constants.  To understand why @('NIL') for example is frequently
 tested, if the test of an @('IF')-expression is computed to have tau <i>s</i>
 then the next question we ask is ``does @('nil') satisfy <i>s</i>?''</p>

 <p>You may determine whether the tau system is spending time executing tau
 predicates by observing the rewriter &mdash; see @(see dmr) &mdash; or by
 interrupting the system and getting a backtrace (see @(see
 set-debugger-enable)).</p>

 <p>If excessive time is being spent in a tau predicate, a draconian solution
 is to disable the @(':')@(tsee executable-counterpart) of that predicate, for
 example in either of these equivalent ways.  The tau system does not execute
 disabled @(':')@(tsee executable-counterpart)s.</p>

 @({
  (in-theory (disable (:executable-counterpart foo)))
  (in-theory (disable (foo)))
 })

 <p>In either case above, you may prefer to provide local @(':')@(tsee
 in-theory) @(':')@(tsee hints) rather than @(':in-theory') @(see events).</p>

 <p>Disabling the executable-counterpart of expensive tau predicates will
 weaken the tau system, probably only negligibly, because it can no longer run
 the predicates to determine whether they admits given constants.</p>

 <p>A more sophisticated solution is to make the tau system record values of
 the @(':')@(tsee logic)-mode function in question, so that the system will
 look up the necessary values rather than running the function every time the
 question arises.  It will look up recorded values whether the
 executable-counterpart of the tau predicate is enabled or disabled.  Here is
 an example of a lemma that can provide such a solution.  See the discussion of
 the <i>Eval</i> form of @(':')@(tsee tau-system) rules.</p>

 @({
  (defthm lemma
    (and (foo 0)
         (foo 17)
         (foo t)
         (not (foo '(a b c))))
    :rule-classes :tau-system)
 })

 <p>It might be difficult to determine <i>which</i> constants are being
 repeatedly tested, although tracing (@(tsee trace$)) suspected tau predicates
 will show what they are being called on.</p>

 <p>At the moment there are no better user-level tools to discover this.
 However, some users may wish to consider the following hack: In the ACL2
 source file @('tau.lisp'), immediately after the definition of the system
 function @('ev-fncall-w-tau-recog'), there is a comment which contains some
 raw Lisp code that can be used to investigate whether tau's use of evaluation
 on constants is causing a problem and to determine which constants are
 involved.</p>

 <p>The second main cause of slowdowns by the tau system is that the system
 contains ``too many'' conjunctive rules (see the <i>Conjunctive</i> form in
 @(tsee tau-system)).  Unfortunately, we have no tools for either identifying
 the problem or addressing it!  That said, let us tell you what we do know!</p>

 <p>Conjunctive rules are used to ``complete'' each tau as it is built.
 Referring to the @('weekdayp') example in @(tsee tau-system), if a tau is
 constructed that recognizes weekdays but not @('MON'), @('TUE'), @('THU'), or
 @('FRI'), it is completed by adding that the tau recognizes (only) @('WED').
 This means that when we construct a tau we scan all known conjunctive rules
 and see whether all but one of the literals of any conjunctive rule are
 present.  This can be expensive.  To mitigate this expense, the tau system
 caches the computation on a per proof basis (the cache is cleared after every
 proof).</p>

 <p>To learn what conjunctive rules there are in your system, evaluate</p>

 @({
  (assoc 'tau-conjunctive-rules (tau-database (w state)))
 })

 <p>Perhaps by sending the implementors that list, we can think of ways to
 index the conjunctive rules to save time.</p>

 <p><i>Dealing with Misapplied Hints</i></p>

 <p>The second common problem caused by the tau system in legacy proof scripts
 is that it can cause subgoals to be renumbered and thus cause hints to be
 missed.  The only ways to address this problem is either to disable the tau
 system (locally or globally by disabling @('(:executable-counterpart
 tau-system)')) or change the legacy hints to use the new subgoal names.</p>")

(defxdoc debugging
  :parents (top)
  :short "Tools for debugging failed or slow proofs, or misbehaving
 functions.")

(defxdoc declare
  :parents (programming acl2-built-ins)
  :short "Extra declarations that can occur in function definitions, @(see let)
  bindings, and so forth."
  :long "<p>Common Lisp provides a declaration mechanism that allows the
 programmer to explain additional information to the compiler.  For
 instance:</p>

 <ul>

 <li>The programmer might declare that some variable always has some particular
 type.  The compiler might then, depending on its optimization/safety settings,
 either add run-time checks to ensure that this really is true, or optimize the
 compiled code by assuming the variable has the correct type.</li>

 <li>The programmer might declare that some variable is @('ignore')d.  The
 compiler might then, instead of warning the programmer that the variable is
 never used, explicitly check to make sure that it really is never used.</li>

 </ul>

 <p>ACL2 supports the above kinds of declarations, and also adds its own kinds
 of declarations for specifying things like the @(see guard)s and @(see
 measure)s of functions, as described in @(see xargs).</p>

 <p>There are also other kinds of Common Lisp declarations that ACL2 does not
 support, e.g., pertaining to inlining, safety settings, variable lifetime, and
 so forth.</p>

 <h3>Usage</h3>

 <p>Examples:</p>

 @({
 (declare (ignore x y z))
 (declare (ignorable x y z)
          (irrelevant w) ; for DEFUN only
          (type integer i j k)
          (type (satisfies integerp) m1 m2))
 (declare (xargs :guard (and (integerp i)
                             (<= 0 i))
                 :guard-hints (("Goal" :use (:instance lemma3
                                               (x (+ i j)))))))
 })

 <p>General Form:</p>

 @({
     (declare d1 ... dn)
 })

 <p>where, in ACL2, each @('di') is of one of the following forms:</p>

 <dl>

 <dt>@('(ignore v1 ... vn)')</dt>

 <dd>where each @('vi') is a variable introduced in the immediately superior
 lexical environment.  These variables must not occur free in the scope of the
 declaration.  This declaration can be useful for inhibiting compiler warnings;
 see also @(see set-ignore-ok).</dd>

 <dt>@('(ignorable v1 ... vn)')</dt>

 <dd>where each @('vi') is a variable introduced in the immediately superior
 lexical environment.  These variables need not occur free in the scope of the
 declaration.  This declaration can be useful for inhibiting compiler warnings;
 see also @(see set-ignore-ok).</dd>

 <dt>@('(irrelevant v1 ... vn)')</dt>

 <dd>where each @('vi') is a formal parameter declared at the top level of a
 surrounding @(tsee defun) form, as shown below.  See @(see irrelevant-formals)
 for more information.</dd>

 <dt>@('(type type-spec v1 ... vn)')</dt>

 <dd>where each @('vi') is a variable introduced in the immediately superior
 lexical environment and @('type-spec') is a type specifier (as described in
 the documentation for @(see type-spec)).  This declaration can be useful for
 optimizing Common Lisp execution speed.  See also @(see the).</dd>

 <dt>@('(xargs :key1 val1 ... :keyn valn)')</dt>

 <dd>where the legal values of the keys and values are described in the
 documentation for @(see xargs).  These declarations are only allowed at the
 top level of definitions (@(tsee defun) and @(tsee defmacro), as shown below),
 and convey information such as the @(see guard) and @(see measure) for a
 function.</dd>

 <dt>@('(optimize ...)')</dt>

 <dd>for example, @('(optimize (safety 3))').  This is allowed only at the top
 level of @(tsee defun) forms and is probably only rarely of any interest.  See
 any Common Lisp documentation for more information.</dd>

 </dl>

 <p>Declarations in ACL2 may occur only where @('dcl') occurs in the following
 display (not including lambda objects, discussed later below, and not showing
 documentation strings here, which are essentially ignored by ACL2)):</p>

 <ul>
 <li>@('(DEFUN name args dcl ... dcl body)')</li>
 <li>@('(DEFMACRO name args dcl ... dcl body)')</li>
 <li>@('(LET ((v1 t1) ...) dcl ... dcl body)')</li>
 <li>@('(MV-LET (v1 ...) term dcl ... dcl body)')</li>
 <li>@('(FLET ((name args dcl ... dcl body) ...))')</li>
 <li>@('(MACROLET ((name args dcl ... dcl body) ...))')</li>
 </ul>

 <p>Each of the cases above permits certain declarations, as follows.</p>

 <ul>

 <li>@('DEFUN'): @(`(cdr (assoc-eq 'defuns *acceptable-dcls-alist*))`)</li>
 <li>@('DEFMACRO'): @(`(cdr (assoc-eq 'defmacro *acceptable-dcls-alist*))`)</li>
 <li>@('LET'): @(`(cdr (assoc-eq 'let *acceptable-dcls-alist*))`)</li>
 <li>@('MV-LET'): @(`(cdr (assoc-eq 'mv-let *acceptable-dcls-alist*))`)</li>
 <li>@('FLET'): @(`(cdr (assoc-eq 'flet *acceptable-dcls-alist*))`)</li>
 <li>@('MACROLET'): @(`(cdr (assoc-eq 'macrolet *acceptable-dcls-alist*))`)</li>
 </ul>

 <p>Of course, declarations are permitted in macro calls to the extent that
 they are permitted in the macroexpansions.  For example, @('declare') forms
 generated by calls of @(tsee let*) and @(tsee case-match) may wind up in
 corresponding @(tsee let) forms in the macroexpansions, where they would be
 subject to the restrictions on @('declare') forms for @('let') shown just
 above.</p>

 <p>Also see @(see lambda) for discussion of lambda objects and their legal
 @('declare') forms.</p>

 <p>@('Declare') is defined in Common Lisp.  See any Common Lisp documentation
 for more information.</p>")

(defxdoc declare-stobjs
  :parents (stobj declare)
  :short "Declaring a formal parameter name to be a single-threaded object"
  :long "<p>When a @(tsee defun) uses one of its formals as a single-threaded
 object (@(see stobj)), the @('defun') <i>must</i> include a declaration that
 the formal is to be so used.  An exception is the formal ``@(tsee state),''
 which if not declared as explained below, may still be used provided an
 appropriate global ``declaration'' is issued: see @(see set-state-ok).</p>

 <p>If the formal in question is @('counters') then an appropriate declaration
 is</p>

 @({
  (declare (xargs :stobjs counters))
 })

 <p>or, more generally,</p>

 @({
  (declare (xargs :stobjs (... counters ...)))
 })

 <p>where all the single-threaded formals are listed.</p>

 <p>For such a declaration to be legal it must be the case that all the names
 have previously been defined as single-threaded objects with @(tsee
 defstobj).</p>

 <p>When an argument is declared to be single-threaded the guard of the
 function is augmented by conjoining to it the condition that the argument
 satisfy the recognizer for the single-threaded object.  Furthermore, the
 syntactic checks done to enforce the legal use of single-threaded objects are
 also sufficient to allow these guard conjuncts to be automatically proved.</p>

 <p>The obvious question arises: Why does ACL2 insist that you declare stobj
 names before using them in @('defun')s if you can only declare names that have
 already been defined with @('defstobj')?  What would go wrong if a formal were
 treated as a single-threaded object if and only if it had already been so
 defined?</p>

 <p>Suppose that one user, say Jones, creates a book in which @('counters') is
 defined as a single-threaded object.  Suppose another user, Smith, creates a
 book in which @('counters') is used as an ordinary formal parameter.  Finally,
 suppose a third user, Brown, wishes to use both books.  If Brown includes
 Jones' book first and then Smith's, then Smith's function treats @('counters')
 as single-threaded.  But if Brown includes Smith's book first, the argument is
 treated as ordinary.</p>

 <p>ACL2 insists on the declaration to ensure that the definition is processed
 the same way no matter what the context.</p>")

(defxdoc defabbrev
  :parents (macros events programming)
  :short "A convenient form of macro definition for simple expansions"
  :long "@({
  Examples:
  (defabbrev snoc (x y) (append y (list x)))
  (defabbrev sq (x) (declare (type (signed-byte 8) x)) (* x x))

  General Form:
  (defabbrev name (v1 ... vn) doc-string decl1 ... declk body)
 })

 <p>where @('name') is a new function symbol, the @('vi') are distinct variable
 symbols, and @('body') is a term.  The @('decli'), if supplied, should be
 legal @('declare') forms; see @(see declare).  @('Doc-string'), if
 non-@('nil'), is an optional string that can provide documentation but is
 essentially ignored by ACL2.</p>

 <p>Roughly speaking, the @('defabbrev') event is akin to defining @('f') so
 that @('(f v1 ... vn) = body').  But rather than do this by adding a new
 axiom, @('defabbrev') defines @('f') to be a macro so that @('(f a1 ... an)')
 expands to @('body'), with the ``formals,'' @('vi'), replaced by the
 ``actuals,'' @('ai').</p>

 <p>For example, if @('snoc') is defined as shown in the first example above,
 then @('(snoc (+ i j) temp)') is just an abbreviation for</p>

 @({
  (append temp (list (+ i j))).
 })

 <p>In order to generate efficiently executable Lisp code, the macro that
 @('defabbrev') introduces uses a @(tsee let) to bind the ``formals'' to the
 ``actuals.''  Consider the second example above.  Logically speaking, @('(sq
 (ack i j))') is an abbreviation for @('(* (ack i j) (ack i j))').  But in fact
 the macro for @('sq') introduced by @('defabbrev') actually arranges for
 @('(sq (ack i j))') to expand to:</p>

 @({
  (let ((x (ack i j)))
    (* x x))
 })

 <p>which executes more efficiently than @('(* (ack i j) (ack i j))').</p>

 <p>In the theorem prover, the @('let') above expands to</p>

 @({
  ((lambda (x) (* x x)) (ack i j))
 })

 <p>and thence to @('(* (ack i j) (ack i j))').</p>

 <p>It is important to note that the term in @('body') should not contain a
 call of @('name') &mdash; i.e., @('defabbrev') should not be used in place of
 @('defun') when the function is recursive.  ACL2 will not complain when the
 @('defabbrev') form is processed, but instead ACL2 will more than likely go
 into an infinite loop during macroexpansion of any form that has a call of
 @('name').</p>

 <p>It is also important to note that the parameters of any call of a macro
 defined by defabbrev will, as is the case for the parameters of a function
 call, be evaluated before the body is evaluated, since this is the evaluation
 order of @(tsee let).  This may lead to some errors or unexpected
 inefficiencies during evaluation if the body contains any conditionally
 evaluated forms like @('cond'), @('case'), or @('if').  Consider the following
 example.</p>

 @({
  (defabbrev foo (x y)
    (if (test x) (bar y) nil))
 })

 <p>Notice a typical one-step expansion of a call of @('foo') (see @(see
 trans1)):</p>

 @({
  ACL2 !>:trans1 (foo expr1 expr2)
   (LET ((X EXPR1) (Y EXPR2))
        (IF (TEST X) (BAR Y) NIL))
  ACL2 !>
 })

 <p>Now imagine that @('expr2') is a complicated expression whose evaluation is
 intended only when the predicate @('test') holds of @('expr1').  The expansion
 above suggests that @('expr2') will always be evaluated by the call @('(foo
 expr1 expr2)'), which may be inefficient (since perhaps we only need that
 value when @('test') is true of @('expr1')).  The evaluation of @('expr2') may
 even cause an error, for example in @(':')@(tsee program) mode if the
 expression @('expr2') has been constructed in a manner that could cause a
 guard violation unless @('test') holds of @('expr1').</p>")

(defxdoc defabsstobj
  :parents (events stobj)
  :short "Define a new abstract single-threaded object"
  :long "<p>We assume familiarity with single-threaded objects; see @(see
 stobj) and see @(see defstobj).  The event @('defabsstobj') defines a
 so-called ``abstract stobj'', a notion we introduce briefly now and then
 explain in more depth below.</p>

 <p>Recall that a @(see defstobj) event produces logical definitions for
 several functions: a recognizer, which characterizes the @(see stobj) in terms
 of lists; a creator, which produces an initial suitable list structure; and
 field accessors and updaters, defined in terms of @(tsee nth) and @(tsee
 update-nth).  @('Defabsstobj') provides a way to define alternate definitions
 for ``stobj primitives'' for a corresponding single-threaded object.  These
 stobj primitives include a recognizer, a creator, and other ``exported''
 functions.  In essence, @('defabsstobj') establishes interface functions, or
 ``exports'', on a new stobj that is a copy of an existing stobj, its
 ``foundation'', which is either <i>concrete</i> (introduced by @(tsee
 defstobj)) or <i>abstract</i> (introduced by @('defabsstobj')).</p>

 <p>We begin below with an introduction to abstract @(see stobj)s.  We then
 explain the @(tsee defabsstobj) event by way of an example.  We conclude by
 giving summary documentation for the @('defabsstobj') event.</p>

 <p>For another introduction to abstract stobjs, see the paper ``Abstract
 Stobjs and Their Application to ISA Modeling'' by Shilpi Goel, Warren A. Hunt,
 Jr., and Matt Kaufmann, in the proceedings of <a
 href='http://www.cs.uwyo.edu/~ruben/acl2-13'>ACL2 Workshop 2013</a>.</p>

 <p><b>INTRODUCTION</b></p>

 <p>We start with a brief review of @(see stobj)s and some potential problems
 with them, followed by an introduction to abstract stobjs and how they can
 avoid these problems.  Prior experience with stobjs will probably help the
 reader to absorb the ideas below.</p>

 <p>Recall that single-threaded objects, or @(see stobj)s, provide a way for
 ACL2 users to stay within the ACL2 logic &mdash; where every data object is an
 atom or a @(tsee cons) of data objects &mdash; while obtaining the benefits of
 fast evaluation through destructive updates.  Consider for example this very
 simple event.</p>

 @({
  (defstobj st fld)
 })

 <p>This event introduces a recognizer, @('stp'), and a creator,
 @('create-st'), for a data structure consisting of a single field accessed and
 updated by functions @('fld') and @('update-fld'), respectively.  Each of
 these four primitive functions has both a logical definition, which is used
 when the prover reasons about the function, and an executable definition,
 which is used in raw Lisp.  In the logic, @('stp') recognizes objects that
 have the requisite fields.  In raw Lisp, there is a ``live stobj'', which is
 typically an array object whose fields correspond to those specified by the
 @(tsee defstobj) event.  (If there is a single stobj field that is an array or
 hash-table field, then that field is the entire stobj in raw Lisp; but we
 ignore that case below.)</p>

 <p>Here are the logical definition and the executable definition,
 respectively, that are introduced for the field accessor, @('fld'), introduced
 above.  Notice that since a stobj is represented in raw Lisp using an array,
 the raw Lisp accessor uses a raw Lisp array accessor, @('svref').  (You can
 see all the logical and executable definitions by evaluating the form
 @('(trace$ defstobj-axiomatic-defs defstobj-raw-defs)') before evaluating the
 @(tsee defstobj) form.)</p>

 @({
  ; logical definition
  (defun fld (st)
    (declare (xargs :guard (stp st)
                    :verify-guards t))
    (nth 0 st))

  ; executable (raw Lisp) definition
  (defun fld (st)
    (svref st 0))
 })

 <p>Sophisticated programming with stobjs can provide efficient implementations
 of algorithms, but may require the preservation of a complex invariant.  One
 can, of course, define a function to implement such an invariant after
 introducing the stobj, as follows.</p>

 @({
  ; Introduce a stobj.
  (defstobj st fld1 ... fldk)

  ; Define an invariant on that stobj.
  (defun good-stp (st)
    (declare (xargs :stobjs st))
    ...)

  ; Define some basic functions that update the stobj and preserve the
  ; invariant.
  (defun update-st (... st ...)
    (declare (xargs :stobjs st
                    :guard (and (good-stp st) ...)))
    ...)
  ...

  ; Prove that the invariant is indeed preserved by those basic functions.
  (defthm good-stp-update-st
    (implies (and (good-stp st)
                  ...)
             (good-stp (update-st ... st ...))))
  ...

  ; Implement algorithms built on the basic functions.
  (defun foo (... st ...)
    (declare (xargs :stobjs st
                    :guard (and (good-stp st) ...)))
    ... (update-st ... st ...) ...)

  ; Prove invariance theorems about these algorithms.
  (defthm good-stp-foo
    (implies (and (good-stp st)
                  ...)
             (good-stp (foo ... st ...))))
  ...

  ; Prove other properties of these algorithms.
  (defthm foo-is-correct
    (implies (and (good-stp st)
                  ...)
             (some-property (foo ... st ...))))
  ...
 })

 <p>But there are at least two potential difficulties in using stobjs as
 described above.</p>

 <ol>

 <li>When @('foo') is executed on concrete data in the ACL2 loop,
 the guard check may be expensive because @('(good-stp st)') is expensive.</li>

 <li>Reasoning about @('foo') (using rules like @('foo-is-correct') above)
 involves proving hypotheses of invariance theorems, which may be complicated
 for the user to manage or slow for the theorem prover.</li>

 </ol>

 <p>The @('defabsstobj') event offers an opportunity to address these issues.
 It introduces a new stobj, which we call an ``abstract stobj'', which is
 associated with a corresponding ``foundational stobj'' introduced by an
 earlier @(tsee defstobj) or @('defabsstobj') event.  The @('defabsstobj')
 event specifies a logical (@(':LOGIC')) and an executable (@(':EXEC'))
 definition for each primitive operation, or ``stobj primitive'', involving
 that stobj.  As is the case for @(tsee defstobj), the logical definition is
 what ACL2 reasons about, and is appropriate to apply to an ACL2 object
 satisfying the logical definition of the recognizer function for the stobj.
 The executable definition is applied in raw Lisp to a live stobj (as discussed
 above).</p>

 <p>Remark.  It is common to use ``a'' and ``c'' in a suffix to suggest
 ``abstract'' and ``concrete'', respectively.  The foundational stobj was, at
 one time, called the ``corresponding concrete stobj''.  That old terminology
 may still be appropriate in the common case that the foundational stobj is a
 concrete stobj (rather than another abstract stobj).  So below, a name like
 @('st$c0') suggests a foundational (``concrete'') stobj for an abstract stobj
 named @('st'), whose abstract stobj recognizer is @('st$ap'), and so on.  End
 of Remark.</p>

 <p>We can picture a sequence of updates to an abstract stobj and its
 foundational stobj.  Initially in this picture, @('st$a0') and @('st$c0') are
 an abstract stobj and its foundation (respectively).  Then an update, @('u1'),
 is applied with @(':LOGIC') and @(':EXEC') functions @('u$a1') and @('u$c1'),
 respectively.  The resulting abstract and foundational stobj, @('st$a1') and
 @('st$c1'), correspond as before.  Then a second update, @('u2'), is applied
 with @(':LOGIC') and @(':EXEC') functions @('u$a2') and @('u$c2'),
 respectively &mdash; again preserving the correspondence.  And so on.</p>

 @({
  Abstract               u$a1       u$a2       u$a3
  (:logic)         st$a0  --> st$a1  --> st$a2  -->   ...

                     ^          ^          ^               ^
  Correspondence     |          |          |          ...  |
                     v          v          v               v

                         u$c1       u$c2       u$c3
  Foundation       st$c0  --> st$c1  --> st$c2  -->   ...
  (:exec)
 })

 <p>We conclude this introduction with some remarks about implementation.
 Consider an abstract stobj @('st') with corresponding foundation @('st$c').
 The live stobjs for @('st') and @('st$c') have the same structure, but are
 distinct arrays.  Indeed, the raw Lisp creator function for @('st$c') is
 called to create a new initial live stobj for @('st').  As we will see below,
 reads and writes in raw Lisp to the live stobj for @('st') are ultimately
 performed using the primitive accessors and updaters defined for @('st$c').
 One might think of the live stobjs for @('st') and @('st$c') as being
 congruent stobjs (see @(see defstobj)), except that the stobjs themselves are
 not truly congruent: in particular, the stobj primitives introduced for
 @('st') may be applied to @('st'), but field updaters of @('st$c') may not.
 As one might expect, the @(':EXEC') function for an exported function is
 applied to the live stobj for @('st') in raw Lisp.</p>

 <p><b>EXAMPLE</b></p>

 <p>We present examples, with detailed comments intended to explain abstract
 stobjs, in two community books: @('books/demos/defabsstobj-example-1.lisp')
 and @('books/demos/defabsstobj-example-2.lisp').  In this section we outline
 the first of these.  We suggest that after you finish this @(see
 documentation) topic, you read through those two books.  There are other books
 @('books/dmeos/defabsstobj-example-*.lisp') that may be helpful to read; in
 particular, @('books/demos/defabsstobj-example-5.lisp') illustrates building
 an abstract stobj on top of another abstract stobj (as its so-called
 ``foundation'', as described below).</p>

 <p>Here is the first of two closely related @('defabsstobj') @(see events)
 from the book @('defabsstobj-example-1.lisp'), but in expanded form.  We will
 show the abbreviated form later, which omits most of the data in the form that
 is immediately below.  Thus most of the information shown here is default
 information.  We believe that the comments below explain most or all of what
 you need to know in order to start using @('defabsstobj'), and that you will
 learn the remainder when you see error messages.  For example, we do not say
 in the comments below that every @(':LOGIC') and @(':EXEC') function must be
 @(see guard)-verified, but that is indeed a requirement.</p>

 <code>
 (defabsstobj st ; The new abstract stobj is named st.

 ; The foundational stobj for st is st$c:

   :foundation st$c

 ; The recognizer for the new abstract stobj is stp, which is defined to be
 ; st$ap in the logic, and is executed on the live stobj in raw Lisp using
 ; st$cp.

   :recognizer (stp :logic st$ap :exec st$cp)

 ; The initial stobj is defined as create-st (a function of no arguments),
 ; which is defined logically as create-st$a, though create-st$c is invoked to
 ; create the initial live stobj for st.  The :correspondence and :preserved
 ; keywords refer to proof obligations, discussed below.

   :creator (create-st :logic create-st$a :exec create-st$c
                       :correspondence create-st{correspondence}
                       :preserved create-st{preserved})

 ; Proof obligations are generated that involve a correspondence between the
 ; new abstract stobj and corresponding foundational stobj.  The function
 ; st$corr, which need not be executable (see :DOC defun-nx), takes two
 ; arguments, a foundational stobj and an abstract stobj.  This function symbol
 ; is used in the statements of the proof obligations.

   :corr-fn st$corr

 ; In this example we have four exports.  In each case a new function is
 ; introduced that has the same signature as its :EXEC function, except that
 ; st$c is replaced by st.  The :LOGIC and :EXEC functions are as specified,
 ; and the other keywords refer to proof obligations that we discuss below.

   :exports ((lookup :logic lookup$a
                     :exec mem$ci
                     :correspondence lookup{correspondence}
                     :guard-thm lookup{guard-thm})
             (update :logic update$a
                     :exec update-mem$ci
                     :correspondence update{correspondence}
                     :preserved update{preserved}
                     :guard-thm update{guard-thm})
             (misc :logic misc$a
                   :exec misc$c
                   :correspondence misc{correspondence})
             (update-misc :logic update-misc$a
                          :exec update-misc$c
                          :correspondence update-misc{correspondence}
                          :preserved update-misc{preserved})))
 </code>

 <p>Note that all stobj primitives (recognizer, creator, and exported
 functions) are defined in the ACL2 loop in terms of their @(':LOGIC')
 functions and in raw Lisp in terms of their @(':EXEC') functions.  In the ACL2
 loop, a @(tsee defun) form defines a function, while in raw Lisp, a @(tsee
 defmacro) form defines a macro (for efficiency).  We first illustrate how that
 works for the recognizer.  (You can see all the logical and executable
 definitions by evaluating the form @('(trace$ defabsstobj-axiomatic-defs
 defabsstobj-raw-defs)') before evaluating the @(tsee defstobj) form.)</p>

 @({
  ; In the ACL2 loop:
  (defun stp (st)
    (declare (xargs :guard 't))
    (st$ap st))

  ; In raw Lisp:
  (defmacro stp (&rest args) (cons 'st$cp args))
 })

 <p>The definitions are made similarly for exported functions.  @(csee Guard)s
 are derived from their @(':LOGIC') functions as follows.  Consider the
 exported function @('update') in our example.  Its @(':LOGIC') function,
 @('update$a'), has formals @('(k val st$a)') and the following guard.</p>

 @({
  (and (and (integerp k) (<= 0 k) (<= k 49))
       (and (integerp val) (<= 0 val))
       (st$ap st$a)
       (mem$c-entryp val))
 })

 <p>The formals of @('update') are obtained by starting with the formals of its
 @(':EXEC') function, @('update-mem$ci') &mdash; which are @('(i v st$c)')
 &mdash; and replacing the foundational stobj name @('st$c') by the new stobj
 name @('st').  The formals of @('update') are thus @('(i v st)').  The guard
 for @('update') is obtained in two steps.  The first step is to substitute the
 formals of @('update') for the formals of @('update$a') in the guard for
 @('update$a'), to obtain the following.</p>

 @({
  (and (and (integerp i) (<= 0 i) (<= i 49))
       (and (integerp v) (<= 0 v))
       (st$ap st)
       (mem$c-entryp v))
 })

 <p>The second step is to replace, for each new stobj primitive @('p'), the
 @(':LOGIC') function for @('p') by @('p') itself.  The only @(':LOGIC')
 function occurring in the formula just above is @('st$ap'), which is the
 @(':LOGIC') function for @('stp').  The guard for @('update') is thus as
 follows.</p>

 @({
  (and (and (integerp i) (<= 0 i) (<= i 49))
       (and (integerp v) (<= 0 v))
       (stp st)
       (mem$c-entryp v))
 })

 <p>Note that the @(':EXEC') version of an abstract @(see stobj) export must
 not include the abstract stobj name among its formals.</p>

 <p>We turn now to the proof obligations, as promised above.  There are three
 types: @(':CORRESPONDENCE'), @(':PRESERVED'), and @(':GUARD-THM').  All
 required lemmas may be printed simply by defining the necessary @(':LOGIC')
 and @(':EXEC') functions and then submitting the @('defabsstobj') event.  (To
 advanced users: also see @(see defabsstobj-missing-events) for a utility that
 returns the required formulas in translated form.)  Although the
 @('defabsstobj') event will fail if the required lemmas have not been proved,
 first it will print the @(tsee defthm) forms that must be admitted in order to
 complete submission of the @('defabsstobj') event.  (Note that although those
 theorems are stated exactly in the form expected by the system, you are
 welcome to supply whatever @(':')@(tsee rule-classes) you prefer, even though
 the system creates @(':rule-classes nil') by default.)</p>

 <p>The detailed theory explaining the need for these lemmas may be found in
 ACL2 source file @('other-events.lisp'), in a comment entitled ``Essay on the
 Correctness of Abstract Stobjs''.  Here, we give an informal sense of the
 importance of these lemmas as we present examples of them.  Fundamental is the
 notion of evaluation in the logic versus evaluation using live stobjs, where
 one imagines tracking the current value of each abstract stobj during each of
 these two evaluations.</p>

 <p>We start with the @(':CORRESPONDENCE') lemmas.  These guarantee that
 evaluation in the logic agrees with evaluation using live stobjs, in the sense
 that the only difference is between a logical stobj and a live stobj, where
 the two correspond in the sense of the function specified by @(':CORR-FN').
 We start with the @(':CREATOR') function where the statement is quite simple,
 stating that the @(':CORR-FN') holds initially.</p>

 @({
  (defthm create-st{correspondence}
    (st$corr (create-st$c) (create-st$a)))
 })

 <p>For the exported functions, there are essentially two cases.  If an
 exported function returns other than the new abstract stobj, then the theorem
 asserts the equality of the results of applying the @(':LOGIC') and @(':EXEC')
 functions for the exported function.  Hypotheses include the @(':CORR-FN')
 correspondence followed by the @(see guard) for the @(':LOGIC') function,
 which is stated in terms of the formal parameters of the @(':EXEC') function
 except using the abstract stobj (here, @('st')) in place of the foundational
 stobj (here, @('st$c')).  The conclusion uses the @(':EXEC') formals, modified
 in the call of the @(':LOGIC') function (here, @('lookup$a')) to use the
 abstract stobj, as in the hypotheses.</p>

 @({
  (defthm lookup{correspondence}
    (implies (and (st$corr st$c st)
                  (integerp i) (<= 0 i) (<= i 49)
                  (st$ap st))
             (equal (mem$ci i st$c)
                    (lookup$a i st)))
    :rule-classes nil)
 })

 <p>By contrast, if the exported function returns the new abstract stobj, then
 the conclusion uses the correspondence function instead of @('EQUAL'), as in
 the following.</p>

 @({
  (defthm update{correspondence}
    (implies (and (st$corr st$c st)
                  (integerp i) (<= 0 i) (<= i 49)
                  (integerp v) (<= 0 v)
                  (st$ap st)
                  (mem$c-entryp v))
             (st$corr (update-mem$ci i v st$c)
                      (update$a i v st)))
    :rule-classes nil)
 })

 <p>For exported functions that return multiple values, such conclusions are
 conjoined together over the returned values.</p>

 <p>The @(':PRESERVED') lemmas guarantee that updates to the abstract stobj
 preserve its recognizer.  The fact that every exported function has this
 property provides justification for an optimization performed by ACL2 during
 generation of proof obligations for @(see guard) verification, by assuming
 that the recognizer always holds.  The @(':PRESERVED') lemma for the
 @(':CREATOR') shows that the recognizer holds initially.</p>

 @({
  (defthm create-st{preserved}
    (st$ap (create-st$a)))
 })

 <p>Here is a typical such lemma, for the exported function @('update').  Note
 that there is no such lemma for @('lookup'), since @('lookup') does not return
 @('st').</p>

 @({
  (defthm update{preserved}
    (implies (and (integerp i) (<= 0 i) (<= i 49)
                  (integerp v) (<= 0 v)
                  (st$ap st)
                  (mem$c-entryp v))
             (st$ap (update$a i v st))))
 })

 <p>Finally, we consider the @(':GUARD-THM') lemmas.  These serve to guarantee
 that the @(see guard) holds for each call of an @(':EXEC') function.  During
 guard verification, logical definitions are used; in particular, since each
 exported function is defined in the logic as the corresponding call of its
 @(':LOGIC') function, guard verification shows that each call of the
 @(':LOGIC') function for an exported function satisfies that function's guard.
 But why is this true for raw Lisp evaluation using live stobjs, where the
 @(':EXEC') function is called for an exported function?  The @(':GUARD-THM')
 lemmas provide the answer, as they state that if the @(':LOGIC') function's
 guard holds, then the @(':EXEC') function's guard holds.  Here is an example.
 Note that the hypotheses come from the correspondence of the foundational and
 abstract function as guaranteed by the @(':CORR') function, together with the
 guard of the @(':LOGIC') function; and the conclusion comes from the guard of
 the @(':EXEC') function.</p>

 @({
  (defthm lookup{guard-thm}
    (implies (and (st$corr st$c c)
                  (integerp i)
                  (<= 0 i)
                  (<= i 49)
                  (st$ap st))
             (and (integerp i)
                  (<= 0 i)
                  (< i (mem$c-length st$c))))
    :rule-classes nil)
 })

 <p>We conclude this EXAMPLE section by showing a short form for the
 @('defabsstobj') form displayed above.</p>

 @({
  (defabsstobj st
    :exports ((lookup :exec mem$ci)
              (update :exec update-mem$ci)
              misc update-misc))
 })

 <p><b>SUMMARY DOCUMENTATION</b></p>

 <p>The General Form is as shown below, where the order of keywords is
 unimportant.  Duplicate keywords are discouraged; while permitted, only the
 first (leftmost) occurrence of a given keyword is used.  Only the
 @(':exports') keyword is required.</p>

 @({
  (defabsstobj st
    :foundation foundation
    :recognizer recognizer
    :creator creator
    :corr-fn corr-fn
    :corr-fn-exists corr-fn-exists
    :congruent-to congruent-to
    :non-executable non-executable
    :protect-default protect-default
    :attachable att
    :exports (e1 ... ek))
 })

 <p>The keyword argument @(':EXPORTS') must be supplied, and missing or
 @('nil') keyword arguments have defaults as indicated below.  All arguments
 must satisfy the conditions below.</p>

 <p>Before we describe the arguments, we define a notion of a ``function spec''
 and its ``completion''.  A function spec is either a symbol or else a list of
 the form</p>

 <code>
 (fn @(':kwd1') val1 ... @(':kwdn') valn), </code>

 <p>that is, a symbol followed by a @(tsee keyword-value-listp).  Each
 @('vali') must be a symbol.  We view the case of a symbol, @('s'), as the
 function spec @('(s)'), with no keywords.  There must be no duplicate
 keywords.  In each case that we expect a function spec, the context provides a
 set of valid keywords for that function spec; it is an error to provide any
 other keyword in the function spec.  Each function spec is interpreted as its
 ``completion'', obtained by extending the function spec with a default value
 for each valid keyword as indicated below.  With that interpretation, the
 ``exported function'' of a function spec is its @('car'), and that function
 symbol and each keyword value must be a guard-verified function symbol; and
 moreover, the @(':EXEC') function must not include the new abstract stobj
 name, @('st'), among its formals.</p>

 <p>We are ready to describe the arguments of @('defabsstobj').</p>

 <blockquote>

 <p>@('St') is a symbol, which names the new abstract stobj.</p>

 <p>@('Foundation') is the name of an existing stobj, which may have been
 introduced either with @(tsee defstobj) or with @('defabsstobj').</p>

 <p>@('Recognizer') is a function spec (for the recognizer function).  The
 valid keywords are @(':LOGIC') and @(':EXEC').  The default for
 @('recognizer') is obtained by adding the suffix @('"P"') to @('name').  The
 default value for @(':LOGIC') is formed by adding the suffix @('"$AP"') to
 @('recognizer'); for @(':EXEC'), by adding the suffix @('"$CP"').  The
 @(':EXEC') function must be the recognizer for the foundational stobj (which
 can be specified using the @(':FOUNDATION') keyword).</p>

 <p>@('Creator') is a function spec (for the creator function).  The valid
 keywords are @(':LOGIC') and @(':EXEC').  The default for @('creator') is
 obtained by adding the prefix @('"CREATE-"') to @('name').  The default
 value for @(':LOGIC') is formed by adding the suffix @('"$A"') to
 @('creator'); for @(':EXEC'), by adding the suffix @('"$C"').  The
 @(':EXEC') function must be the creator for the foundational stobj (which can
 be specified using the @(':FOUNDATION') keyword).</p>

 <p>@('Corr-fn') is a known function symbol that takes two arguments (for the
 correspondence theorems).  The default for @('corr-fn') is obtained by adding
 the suffix @('"$CORR"') to @('name').</p>

 <p>@('Corr-fn-exists') is a Boolean with default @('nil'), which will
 generally serve well.  See @(see stobj-attachment-restrictions) for a
 discussion of this argument.</p>

 <p>@('Congruent-to') should either be @('nil') (the default) or the name of an
 abstract stobj previously introduced (by @(tsee defabsstobj)).  In the latter
 case, the current and previous abstract stobj should have the same
 foundational stobj (not merely congruent foundational stobjs), and their
 @(':EXPORTS') fields should have the same length and also correspond, as
 follows: the ith export of each should have the same @(':LOGIC') and
 @(':EXEC') symbols.  See @(see defstobj) for more about congruent stobjs.
 Note that if two names are congruent, then they are either both ordinary
 stobjs or both abstract stobjs.</p>

 <p>@('Non-executable') should either be @('nil') (the default) or @('t').
 When @('t'), a global stobj is not created for the given name; see @(see
 defstobj), Section &ldquo;Specifying Non-executable Stobjs&rdquo;, for
 details, as the meaning of @(':non-executable') is the same for
 @('defabsstobj') as it is for @('defstobj').</p>

 <p>@('Protect-default') should either be @('nil') (the default) or @('t').  It
 provides the value of keyword @(':PROTECT') for each member of @('exports')
 that does not explicitly specify @(':PROTECT').  See the discussion of
 @('exports') below.</p>

 <p>@('Attachable') should be @('nil') (the default) or @('t').  See @(see
 attach-stobj) for a discussion of this keyword.</p>

 <p>An important aspect of the @('congruent-to') parameter is that if it is not
 @('nil'), then the checks for lemmas &mdash; @('{CORRESPONDENCE}'),
 @('{GUARD-THM}'), and @('{PRESERVED}') &mdash; are omitted.  Thus, the values
 of keywords @(':CORR-FN') and @(':CORR-FN-EXISTS'), and the values of keywords
 @(':CORRESPONDENCE'), @(':GUARD-THM'), and @(':PRESERVED') in each export (as
 we discuss next), are irrelevant; they are not inferred and they need not be
 supplied.</p>

 <p>The value of @(':EXPORTS') is a non-empty true list.  Each @('ei') is a
 function spec (for an exported function).  The valid keywords are @(':LOGIC'),
 @(':EXEC'), @(':CORRESPONDENCE'), @(':GUARD-THM'), @(':PROTECT'), and
 @(':UPDATER'), and also @(':PRESERVED') if and only if the specified
 @(':EXEC') function returns the foundational stobj.  The default values for
 all of these keywords except @(':UPDATER') and @(':PROTECT') are obtained by
 respectively adding the suffix @('"$A"') @('"$C"'),
 @('"{CORRESPONDENCE}"'), @('"{GUARD-THM}"'), or @('"{PRESERVED}"').  For
 @(':PROTECT'), the default is @('nil') unless the @('defabsstobj') event
 specifies @(':PROTECT-DEFAULT t').  If @(':UPDATER upd') is supplied and
 @('upd') is not @('nil'), then function exported by the function spec is a
 child stobj accessor whose corresponding updater is @('upd'); see the
 discussion of @(':UPDATER') in @(see nested-stobjs).</p>

 </blockquote>

 <p>Not shown is the keyword, @(':MISSING'); the effect of @(':missing t') is
 to turn the call of @('defabsstobj') into a corresponding call of @(tsee
 defabsstobj-missing-events).</p>

 <p>Note that a @('defabsstobj') event will fail if the required lemmas &mdash;
 that is, those for valid keywords @(':CORRESPONDENCE'), @(':GUARD-THM'), and
 @(':PRESERVED') &mdash; have not been proved, unless proofs are being skipped.
 The exemption when skipping proofs allows the supporting lemmas to be @(tsee
 local) to @(see books) and @(tsee encapsulate) @(see events).  If the @(tsee
 ld) special @(tsee ld-skip-proofsp) is @('t'), then the missing @(see events)
 are printed with a warning before the @('defabsstobj') event is admitted; but
 if @('ld-skip-proofsp') is the symbol @('INCLUDE-BOOK'), then that warning is
 omitted.  (Also see @(see skip-proofs) and see @(see ld-skip-proofsp).)  If
 however proofs are not being skipped, then the @('defabsstobj') event will
 fail after printing the missing events.  Advanced users may wish to see @(see
 defabsstobj-missing-events) for a utility that returns a data structure
 containing the missing lemmas.</p>

 <p>Let @('st') be an abstract stobj with corresponding foundational stobj
 @('st$c').  Let @('f') be an exported function for @('st') and let @('f$a')
 and @('f$c') be the corresponding @(':LOGIC') and @(':EXEC') functions,
 respectively.  The formals of @('f') are obtained by taking the formals of
 @('f$c') and replacing @('st$c') by @('st').  The @(see guard) for @('f') is
 derived as follows from the guard of @('f$a').  First, the formals of @('f$a')
 are replaced by the formals of @('f') in the guard of @('f$a'), to obtain a
 term we denote here as @('guard-pre').  Now for each exported function symbol
 @('g') of @('st') with corresponding @(':LOGIC') function @('g$a'), form a
 functional substitution by consing @('g$a') with @('g').  Finally, apply that
 functional substitution to @('guard-pre'); the result is the guard of @('f').
 That guard must satisfy the usual conditions of a guard: thus, it must return
 a single non-@(see stobj) value and satisfy normal syntactic restrictions,
 including single-threadedness in its handling of stobjs.</p>

 <p>@('Remark').  Because of how guards are created for exported functions, and
 in particular because @(':LOGIC') functions are replaced as discussed above, a
 good discipline is to define @(':LOGIC') functions that are not intended for
 general use, but are intended only for use as @(':LOGIC') functions of
 corresponding stobj primitives.  For example, suppose that you use @('length')
 as the @(':LOGIC') function for some stobj primitive, @('f') (as opposed to
 using your own function, say, @('foo-length') or @('foo$a')).  Then every call
 of @('length') will be replaced by @('f') when creating the guard of a stobj
 primitive from the guard of its @(':LOGIC') function.  This might not be what
 you intended if you were using @('length') in that guard simply to compute the
 length of an ordinary list.</p>

 <p>Additional restrictions include the following.</p>

 <ul>

 <li>All exported function names must be new (unless redefinition is on; see
 @(see ld-redefinition-action)), and there must be no duplicates among
 them.</li>

 <li>The foundational stobj name must be a formal parameter of the @(':EXEC')
 function of every function spec, except for the @(':CREATOR') function
 spec.</li>

 <li>The @(':LOGIC') and @(':EXEC') function for a function spec must agree on
 both the number of inputs and the number of outputs.</li>

 <li>The foundational stobj must not be a @(see declare)d stobj of the
 @(':LOGIC') function of any function spec.  (This restriction could perhaps be
 removed, but it is convenient for the implementation of the events generated
 by a call of @('defabsstobj').)</li>

 <li>The @(':PROTECT') keyword is something that you should ignore unless you
 get an error message about it, pertaining to modifying the foundational stobj
 non-atomically.  In that case, you can eliminate the error by providing
 @(':PROTECT t') in the function spec, or by providing @('defabsstobj') keyword
 argument @(':PROTECT-DEFAULT t') at the top level, in order to restore the
 required atomicity.  The above explanation is probably all you need to know
 about @(':PROTECT'), but just below is a more complete explanation for those
 who desire it.  Further information is also available if you need it; see
 @(see set-absstobj-debug), and see the example uses of these keywords in
 community book @('books/demos/defabsstobj-example-2.lisp').</li>

 </ul>

 <p>For those who are interested, here is a more detailed discussion of
 @(':PROTECT') and @(':PROTECT-DEFAULT'), as promised above.  It applies to any
 function spec for an export (hence not to the @(':CREATOR') function spec).
 If the @(':EXEC') function is a stobj primitive, then clearly the following
 property holds: any execution of a call of that function can only update the
 foundational stobj at most once &mdash; i.e., modification of the foundational
 stobj is atomic.  ACL2 can deduce this property not only for stobj primitives
 but for many other functions as well.  However, if ACL2 cannot deduce this
 property, then it will cause an error saying that the @(':EXEC') function
 ``appears capable of modifying the foundational stobj, @('<stobj_name>'),
 non-atomically.''  That message also explains how to eliminate this error:
 provide @(':PROTECT t') for the function spec.  Alternatively, all function
 specs without an explicit @(':PROTECT') keyword can be implicitly supplied
 @(':PROTECT t') by supplying the value @('t') for the @(':PROTECT-DEFAULT')
 keyword parameter of the @('defabsstobj') event.  However, beware that when
 @(':PROTECT') is @('t'), the generated raw Lisp code runs slightly less
 efficiently &mdash; though perhaps with negligible efficiency loss if the
 @(':EXEC') function is not trivial.  Community books
 @('books/demos/defabsstobj-example-3.lisp') and
 @('books/demos/defabsstobj-example-4.lisp') provide related information.  Also
 see @(see set-absstobj-debug) for a potentially dangerous way to eliminate
 that inefficiency using argument @(':ignore').</p>

 <p>We conclude with some remarks.</p>

 <p>Unlike @(tsee defstobj), there is no @(':renaming') argument.  Instead, the
 scheme described above provides a flexible way to assign names.  Also unlike
 @(tsee defstobj), there is no @(':inline') or @(':non-memoizable') argument;
 @(':inline') is essentially t, in the sense that stobj primitives are macros
 in raw Lisp; and the @(':non-memoizable') argument is derived implicitly, to
 agree with non-memoizability of the foundational stobj.</p>

 <p>Those who use @(see hons-enabled) features, including function
 memoization (see @(see memoize)), may be aware that the memo table for a
 function is flushed whenever it is the case that one of its stobj inputs is
 updated.  In fact, such flushing happens even when a stobj that is congruent
 to one of its stobj inputs is updated.  For that purpose, an abstract stobj is
 considered to be congruent to its foundational stobj.</p>")

(defxdoc defabsstobj-missing-events
  :parents (events)
  :short "Obtain the @(see events) needed to admit a @(tsee defabsstobj) event"
  :long "<p>We assume familiarity with @(tsee defabsstobj).
 @('Defabsstobj-missing-events') is a macro is for advanced users (who, for
 example, understand the role of the @('translate') and @('untranslate')
 functions), who want programmatic access to the @(tsee defthm) events required
 to admit a specific @('defabsstobj') event.</p>

 <p>This macro has the same syntax as @(tsee defabsstobj) &mdash; to use it,
 just replace a call of @(tsee defabsstobj) by a call of
 @('defabsstobj-missing-events') on the same arguments.  The result is an error
 triple @('(mv erp val state)').  If @('erp') is @('nil'), then @('val') is the
 list of all objects @('(name formula . old-formula)'), where a @(tsee defthm)
 event named @('name') remains to be admitted whose translated formula is
 @('formula'), and where @('old-formula') is @('nil') unless the indicated
 event already exists (hence with a different formula), in which case
 @('old-formula') is the existing translated formula.</p>

 <p>To build a @(tsee defthm) event from the above value, @('val'), we suggest
 evaluating a form like @('(untranslate formula t (w state))').</p>")

(defxdoc defattach
  :parents (events)
  :short "Execute constrained functions using corresponding attached functions"
  :long "
 @({
  General Forms:
  (defattach f g)   ; single attach or, if g is nil, unattach
  (defattach (f1 g1 :kwd val ...)
             ...
             (fk gk :kwd' val' ...)
             :kwd'' val'' ...)
 })

 <p>where each indicated keyword-value pair is optional and each keyword is in
 the list @(`*defattach-keys-extended*`).  More details are in the ``Syntax and
 Semantics'' section below.</p>

 <p>A related utility can cause a function call to be evaluated using an
 alternate, provably equal function.  See @(see memoize), option
 @(':INVOKE').</p>

 <p>This @(see documentation) topic is organized into the following
 sections:</p>

 <ul>

 <li>Introductory Example.</li>

 <li>Syntax and Semantics of Defattach.</li>

 <li>Three Primary Uses of Defattach.</li>

 <li>Miscellaneous Remarks, with discussion of possible user errors.</li>

 </ul>

 <p>Please see @(see encapsulate) if you intend to use @('defattach') but are
 not already familiar with the use of @('encapsulate') to introduce constrained
 functions.  It may also be helpful to see @(see evaluation).</p>

 <p>See community book @('books/misc/defattach-example.lisp') for a small
 example.  it illustrates how @('defattach') may be used to build something
 like ``higher-order'' programs, in which constrained functions may be refined
 to different executable functions.  More uses of @('defattach') may be found
 in the ACL2 source code, specifically, file @('boot-strap-pass-2-a.lisp').</p>

 <h3>Introductory Example.</h3>

 <p>We begin with a short log illustrating the use of @('defattach').  Notice
 that after evaluating the event @('(defattach f g)'), a call of the
 constrained function @('f') is evaluated by instead calling @('g') on the
 arguments.</p>

 @({
  ACL2 !>(encapsulate
          ((f (x) t :guard (true-listp x)))
          (local (defun f (x) x))
          (defthm f-property
            (implies (consp x) (consp (f x)))))
  [... output omitted ...]
   T
  ACL2 !>(defun g (x)
           (declare (xargs :guard (or (consp x) (null x))))
           (cons 17 (car x)))
  [... output omitted ...]
   G
  ACL2 !>(f '(3 4)) ; undefined function error

  ACL2 Error in TOP-LEVEL:  ACL2 cannot ev the call of undefined function
  F on argument list:

  ((3 4))

  To debug see :DOC print-gv, see :DOC trace, and see :DOC wet.

  ACL2 !>(defattach f g)
  [... output omitted ...]
   :ATTACHMENTS-RECORDED
  ACL2 !>(f '(3 4)) ; f is evaluated using g
  (17 . 3)
  ACL2 !>(trace$ f g)
   ((F) (G))
  ACL2 !>(f '(3 4)) ; f is evaluated using g
  1> (ACL2_*1*_ACL2::F (3 4))
    2> (ACL2_*1*_ACL2::G (3 4))
      3> (G (3 4))
      <3 (G (17 . 3))
    <2 (ACL2_*1*_ACL2::G (17 . 3))
  <1 (ACL2_*1*_ACL2::F (17 . 3))
  (17 . 3)
  ACL2 !>(defattach f nil) ; unattach f (remove its attachment)
  [... output omitted ...]
   :ATTACHMENTS-RECORDED
  ACL2 !>(f '(3 4)) ; undefined function error once again
  1> (ACL2_*1*_ACL2::F (3 4))

  ACL2 Error in TOP-LEVEL:  ACL2 cannot ev the call of undefined function
  F on argument list:

  ((3 4))

  To debug see :DOC print-gv, see :DOC trace, and see :DOC wet.

  ACL2 !>
 })

 <h3>Syntax and Semantics of Defattach.</h3>

 <p>The log above shows that the event @('(defattach f g)') allows @('g') to be
 used for evaluating calls of @('f').  From a logical perspective, the
 evaluation takes place in the addition to the current session of an
 ``attachment equation'' axiom (universally quantified over all @('x')) for
 each @('defattach') event:</p>

 @({
  (equal (f x) (g x)) ;;; attachment equation axiom for (defattach f g)
 })

 <p>Below we explain @('defattach') in some detail.  But it is important to
 keep in mind that evaluation with the attachment equations takes place in an
 extension of the logical theory of the session.  ACL2 guarantees that this
 so-called ``evaluation theory'' remains consistent, assuming the absence of
 @(tsee defaxiom) @(see events) from the user.  This guarantee is a consequence
 of a more general guarantee: an ACL2 logical @(see world) exists in which
 (loosely speaking) the attachment equation for @('(defattach f g)'), as
 @('(defun f (...) (g ...))'), takes the place of the original defining event
 for @('f'), for each @('defattach') event.  This more general guarantee holds
 even if there are @(tsee defaxiom) events, though as explained below, no
 function symbol that syntactically supports a @('defaxiom') formula is allowed
 to get an attachment.  A deeper discussion of the logical issues is available
 (but not intended to be read by most users) in a long comment in the ACL2
 source code labeled ``Essay on Defattach.''</p>

 @({
  Example Forms:
  (defattach f g)   ; call g in place of calling constrained function f
  (defattach (f g)) ; same as just above
  (defattach (f g :hints (("Goal" :in-theory (enable foo)))))
                    ; equivalent to first form above, except with hints for the
                    ; proof that the guard of f implies the guard of g
  (defattach (f g :hints (("Goal" :in-theory (enable foo)))
                  :otf-flg t))
                    ; as above, except with an :otf-flg of t for the proof that
                    ; the guard of f implies the guard of g
  (defattach (f g)
             :hints (("Goal" :use my-thm)))
                    ; equivalent to first form above, except with hints for the
                    ; proof that the constraints on f hold for g
  (defattach (f g)
             :hints (("Goal" :use my-thm))
             :otf-flg t)
                    ; as above, except with an :otf-flg of t for the proof that
                    ; the constraints on f hold for g
  (defattach (f g)
             (h j)) ; Attach g to f and attach j to h
  (defattach (f g :attach nil)
             (h j)) ; Same as just above, including the same proof obligations,
                    ; except for one difference: because of :attach nil, calls
                    ; of f will not be evaluated, i.e., there will be no
                    ; executable attachment of g to f
  (defattach (f nil)
             (h j)) ; Attach j to h and unattach f
  (defattach (f g :hints (("Goal" :in-theory (enable foo))))
             (h j :hints (("Goal" :in-theory (enable bar))))
             :hints (("Goal" :use my-thm)))
                    ; Attach g to f and attach j to h, with hints:
                    ; - For proving that the guard of f implies the guard of g,
                    ;   enable foo;
                    ; - For proving that the guard of h implies the guard of j,
                    ;   enable bar; and
                    ; - For proving that the constraints on f and h hold for
                    ;   g and j (respectively), use theorem my-thm.

  (defattach f nil)   ; remove the attachment of f, if any (e.g., g above)
  (defattach (f nil)) ; same as just above

  General Forms:
  (defattach f g)   ; single attach or, if g is nil, unattach
  (defattach (f1 g1 :kwd11 val11 ...)
             ...
             (fk gk :kwdk1 valk1 ...)
             :kwd1 val1 ...)
 })

 <p>where each indicated keyword-value pair is optional and each keyword is in
 the list @(`*defattach-keys-extended*`).  We distinguish between keywords
 within the @('(fi gi :kwdi1 vali1 ...)'), which we call <i>guard keywords</i>,
 and keywords at the top level, shown above as @(':kwd1 val1 ...'), which we
 call <i>top-level keywords</i>.</p>

 <ul>

 <li>The guard keywords are in the list @(`*defattach-keys*`).  The
 @(':')@(tsee hints), @(':')@(tsee instructions), and @(':')@(tsee otf-flg)
 keywords in @('(fi gi ...)') are used in the proofs of the guard proof
 obligation for the attachment of @('gi') to @('fi').  They have their usual
 values and meanings, as when used (for example) in @(tsee defthm) @(tsee
 events).  The value of each @(':attach') keyword is either @('t') or @('nil').
 We discuss the @(':attach') keyword later in this @(see documentation)
 topic.</li>

 <li>The top-level keywords @(':hints'), @(':instructions'), and @(':otf-flg')
 are used in the constraint proof obligations just as described above for the
 guard proof obligations.  When @(':attach') is used as a top-level keyword,
 its value serves as a default for entries @('(fi gi ...)') that do not specify
 @(':attach').  @(':Skip-checks') and @(':system-ok') are described below.</li>

 </ul>

 <p>No keyword may occur twice in the same context: that is, neither twice as a
 guard keyword in the same @('(fi gi ...)')  entry, nor twice as a top-level
 keyword.  Moreover, @(':instructions') may not occur in the same context with
 @(':hints') or @(':otf-flg').</p>

 <p>The argument @(':skip-checks t') enables easy experimentation with
 @('defattach'), by permitting use of @(':')@(tsee program) mode functions and
 the skipping of semantic checks.  Also permitted is @(':skip-checks nil') (the
 default) and @(':skip-checks :cycles'), which turns off only the update of the
 extended ancestor relation (defined below) and hence the check for cycles in
 this relation (which is discussed below).  We do not make any logical claims
 when the value of @(':skip-checks') is non-@('nil'); indeed, a trust tag is
 then required (see @(see defttag)).  Note that the interaction of @(see
 memoization) and attachments is not tracked for attachments introduced with a
 non-@('nil') value of @(':skip-checks').  For more discussion of
 @(':skip-checks t'), see @(see defproxy); we do not discuss @(':skip-checks')
 further, here.</p>

 <p>The argument @(':system-ok t') allows attachment to system functions.
 Without this argument, the @('defattach') event will fail if any @('fi') is a
 built-in ACL2 function.  Rather than supplying this argument directly, it is
 recommended to use @(tsee defattach-system), which has the same syntax as
 @('defattach') with two exceptions: it adds @(':system-ok t') automatically,
 that is, @(':system-ok') is implicit; and it expands to a @(tsee local) call
 of @('defattach').  The latter is important so that the attachment does not
 affect system behavior outside a book containing the @('defattach') event.  Of
 course, if it is truly intended to affect such behavior, the argument
 @(':system-ok t') may be given directly to @('defattach'), without a
 surrounding use of @('local').</p>

 <p>The first General Form above is simply an abbreviation for the form
 @('(defattach (f g))'), which is an instance of the second General Form above.
 For the second General Form we say that @('gi') is ``attached to'' @('fi') (by
 the @('defattach') event) if @('gi') is not @('nil'), and otherwise we say
 that @('fi') is ``unattached'' (by the @('defattach') event).  It is also
 convenient to refer to @('<fi,gi>') as an ``attachment pair'' (of the event)
 if @('gi') is not @('nil').  We may refer to the set of @('fi') as the
 ``attachment nest'' of each @('fi').</p>

 <p>We start with a brief introduction to the first General Form in the case
 that @('g') is not @('nil').  This form arranges that during evaluation, with
 exceptions noted below, every call of the constrained function symbol @('f')
 will in essence be replaced by a call of the function symbol @('g') on the
 same arguments.  We may then refer to @('g') as the ``attachment of'' @('f'),
 or say that ``@('g') is attached to @('f').''  Notable exceptions, where we do
 not use attachments during evaluation, are for macroexpansion, evaluation of
 @(tsee defconst) and @(tsee defpkg) terms, evaluation during @(tsee table)
 events, some @(see stobj) operations including all <see topic='@(url
 STOBJ)'>updates</see>, and especially evaluation of ground terms (terms
 without free variables) during proofs.  However, even for these cases we allow
 the use of attachments in the first argument of @(tsee prog2$) and, more
 generally, the next-to-last (i.e., second) argument of @(tsee return-last)
 when its first argument is not of the form @(''m') for some macro, @('m').</p>

 <p>To see why attachments are disallowed during evaluation of ground terms
 during proofs (except for the @(tsee prog2$) and @(tsee return-last) cases
 mentioned above), consider the following example.</p>

 @({
  (defstub f (x) t)
  (defun g (x) (+ 3 x))
  (defattach f g)
 })

 <p>If the form @('(f 2)') is submitted at the ACL2 prompt, the result will be
 @('5') because the attachment @('g') of @('f') is called on the argument,
 @('2').  However, during a proof the term @('(f 2)') will not be simplified to
 @('5'), since that would be unsound, as there are no axioms about @('f') that
 would justify such a simplification.</p>

 <p>For the case that @('g') is @('nil') in the first General Form above, the
 result is the removal of the existing attachment to @('f'), if any.  After
 this removal, calls of @('f') will once again cause errors saying that ``ACL2
 cannot ev the call of undefined function @('f') ...''.  In this case not only
 is the previous attachment to @('f') removed; moreover, for every function
 symbol @('f'') in the attachment nest of @('f') in the @('defattach') event
 that introduced the existing attachment to @('f'), then @('f'') is unattached.
 (An example near the end of this @(see documentation) topic shows why this
 unattachment needs to be done.) Such removal takes place before the current
 @('defattach') is processed, but is restored if the new event fails to be
 admitted.</p>

 <p>We focus henceforth on the second General Form.  There must be at least one
 attachment, i.e., @('i') must be at least 1.  All keywords are optional; their
 role is described below.  The @('fi') must be distinct constrained function
 symbols, that is, function symbols all introduced in @(see signature)s of
 @(tsee encapsulate) @(see events) (or macros such as @(tsee defstub) that
 generate @(tsee encapsulate) events).  Each non-@('nil') @('gi') is a
 @(':')@(tsee logic)-mode function symbol that has had its guards verified,
 with the same @(see signature) as @('fi') (though formal parameters for
 @('fi') and @('gi') may have different names).  (Note: The macro
 @('defattach!'), defined in community book @('books/misc/defattach-bang'),
 avoids this restriction.)  This event generates proof obligations and an
 ordering check, both described below.  The effect of this event is first to
 remove any existing attachments for all the function symbols @('fi'), as
 described above for the first General Form, and then to attach each @('gi') to
 @('fi').</p>

 <p>Proof obligations must be checked before making attachments.  For this
 discussion we assume that each @('gi') is non-@('nil') (otherwise first remove
 all attachment pairs @('<fi,gi>') for which @('gi') is nil).  Let @('s') be
 the functional substitution mapping each @('fi') to @('gi').  For any term
 @('u'), we write @('u\s') for the result of applying @('s') to @('u'); that
 is, @('u\s') is the ``functional instance'' obtained by replacing each
 @('fi') by @('gi') in @('u').  Let @('G_fi') and @('G_gi') be the guards of
 @('fi') and @('gi'), respectively.  Let @('G_fi'') be the result of replacing
 each formal of @('fi') by the corresponding formal of @('gi') in @('G_fi').
 ACL2 first proves, for each @('i') (in order), the formula @('(implies G_fi'
 G_gi)\s').  If this sequence of proofs succeeds, then the remaining formula
 to prove is the functional instance @('C\s') of the conjunction @('C') of the
 constraints on the symbols @('fi'); see @(see constraint).  This last proof
 obligation is thus similar to the one generated by functional instantiation
 (see @(see constraint)).  As with functional instantiation, ACL2 stores the
 fact that such proofs have been done so that they are avoided in future events
 (see @(see lemma-instance)).  Thus, you will likely avoid some proofs with the
 sequence</p>

 @({
  (defattach f g)
  (defattach f nil)
  (defattach f g)
  (defattach f nil)
  ...
 })

 <p>rather than the sequence:</p>

 @({
  (defattach f g)
  :u
  (defattach f g)
  :u
  ...
 })

 <p>It remains to describe an ordering check.  We begin with the following
 motivating example.</p>

 @({
  (defstub f (x) t) ; constrained function with no constraints
  (defun g (x) (declare (xargs :guard t)) (not (f x)))
  (defattach f g) ; ILLEGAL!
 })

 <p>Were the above @('defattach') event to succeed, the evaluation theory
 (discussed above) would be inconsistent: @('(f x)') equals @('(g x)') by the
 new attachment equation, which in turn equals @('(not (f x))') by definition
 of @('g').  The evaluation would therefore be meaningless.  Also, from a
 practical perspective, there would be an infinite loop resulting from any call
 of @('f').</p>

 <p>We consider a function symbol @('g') to be an <i>extended immediate
 ancestor of</i> a function symbol @('f') if either of the following two
 criteria is met: (a) @('g') occurs in the formula that introduces
 @('f') (i.e., definition body or constraint) and @('g') is introduced by an
 event different from (earlier than) the event introducing @('f'); or (b)
 @('g') is attached to @('f').  We also consider @('g') to be an extended
 immediate ancestor of @('f') if there are function symbols @('f'') and @('g'')
 that are introduced in the same events as @('f') and @('g'),
 respectively (such as the same @(tsee mutual-recursion) or the same @(tsee
 encapsulate) with non-empty signatures), such that @('g'') is an extended
 immediate ancestor of @('f'') in the sense above.  For a proposed
 @('defattach') event, we check that the graph defined by this relation has no
 cycles, where for condition (b) we include all attachment pairs that would
 result, including those remaining from earlier @('defattach') events.</p>

 <p>Of course, a special case is that no function symbol may be attached to
 itself.  Similarly, no function symbol may be attached to any of its
 ``siblings'' &mdash; function symbols introduced by the same event &mdash; as
 siblings are considered equivalent for purposes of the acyclicity check.</p>

 <h3>Three Primary Uses of Defattach.</h3>

 <p>We anticipate three uses of @('defattach'):</p>

 <ol>

 <li>Constrained function execution</li>

 <li>Sound modification of the ACL2 system</li>

 <li>Program refinement</li>

 </ol>

 <p>We discuss these in turn.</p>

 <ol>

 <li>The example at the beginning of this @(see documentation) illustrates
 constrained function execution.</li>

 <li>ACL2 is written essentially in itself.  Thus, there is an opportunity to
 attach to system functions.  For example, encapsulated function
 @('too-many-ifs-post-rewrite'), in the ACL2 source code, receives an
 attachment of @('too-many-ifs-post-rewrite-builtin'), which implements a
 heuristic used in the rewriter.  See @(see system-attachments).  To find all
 such examples, search the source code for the string `-builtin'.<br/>

 Over time, we expect to continue replacing ACL2 source code in a similar
 manner.  We invite the ACL2 community to assist in this ``open architecture''
 enterprise; feel free to email the ACL2 implementors if you are interested in
 such activity.</li>

 <li>Recall that for an attachment pair @('<f,g>'), a proof obligation is
 (speaking informally) that @('g') satisfies the constraint on @('f').  Yet
 more informally speaking, @('g') is ``more defined'' than @('f'); we can think
 of @('g') as ``refining'' @('f').  With these informal notions as motivation,
 we can view defattach as providing refinement through the following formal
 observation: the evaluation theory extends the theory of the ACL2 session,
 specifically by the addition of all attachment equations.  For the
 logic-inclined, it may be useful to think model-theoretically: The class of
 models of the evaluation theory is non-empty but is a subset of the class of
 models of the current session theory.</li>

 </ol>

 <h3>Miscellaneous Remarks, with discussion of possible user errors.</h3>

 <p>We conclude with remarks on some details.</p>

 <p>A @('defattach') event is never redundant (see @(see redundant-events)); in
 that sense it is analogous to @(tsee in-theory).</p>

 <p>As mentioned above, the use of attachments is disabled for evaluation of
 ground terms during proofs.  However, attachments can be used on code during
 the proof process, essentially when the ``program refinement'' is on theorem
 prover code rather than on functions we are reasoning about.  The attachment
 to @('too-many-ifs-post-rewrite') described above provides one example of such
 attachments.  Another example is that a meta function or clause-processor
 function can call functions that have attachments, with a restriction that
 those attached functions must not also be ancestral in a corresponding
 evaluator.  See @(see evaluator-restrictions) for a discussion of that
 restriction, and see @(see transparent-functions) for a device that can relax
 the restriction (while imposing additional requirements on attachments).</p>

 <p>For an attachment pair @('<f,g>'), evaluation of @('f') never consults the
 @(see guard) of @('f').  Rather, control passes to @('g'), whose guard is
 checked if necessary.  The proof obligation related to guards, as described
 above, guarantees that any legal call of @('f') is also a legal call of
 @('g').  Thus for guard-verified code that results in calls of @('f') in raw
 Lisp, it is sound to replace these calls with corresponding calls of
 @('g').</p>

 <p>@('Defattach') events are illegal inside any @(tsee encapsulate) event with
 a non-empty @(see signature) unless they are @(see local) to the @(tsee
 encapsulate).</p>

 <p>(Of interest only to users of @(tsee apply$).)  Special handling is applied
 when attempting to attach to a so-called <i>warrant</i>, which is produced by
 an application of @(tsee defwarrant) (or @(tsee defun$)).  In that case it is
 legal to attach the function @('true-apply$-warrant') to the warrant, without
 any proof obligation.  This attachment is actually performed automatically by
 @('defwarrant'), so users (even users of @('apply$')) need not deal
 explicitly with such attachments.  However, these attachments make warrants
 executable in the loop; for example, after @('(defwarrant foo)'), @('(warrant
 foo)') will evaluate to @('t') in the loop.</p>

 <p>We next discuss a restriction based on a notion of a function symbol
 syntactically supporting an event.  Function symbol @('f') is <i>ancestral</i>
 in event @('E') if either @('f') occurs in @('E'), or (recursively) @('f')
 occurs in an event @('E'') that introduces some function symbol @('g') that is
 ancestral in @('E').  We require that no function symbol ancestral in the
 formula of a @(tsee defaxiom) event may have an attachment.  Theoretical
 reasons are discussed in comments in the ACL2 source code, but here we give a
 little example showing the need for some such restriction: without it, we show
 how to prove @('nil')!</p>

 @({
  (defn g1 () 1)
  (defn g2 () 2)
  (defstub f1 () t)
  (defstub f2 () t)
  (defund p (x)
    (declare (ignore x))
    t)
  (defevaluator evl evl-list
    ((p x)))
  (defaxiom f1-is-f2
    (equal (f1) (f2)))
  (defun meta-fn (x)
    (cond ((equal (f1) (f2))
           x)
          (t *nil*)))
  (defthm bad-meta-rule
    (equal (evl x a)
           (evl (meta-fn x) a))
    :rule-classes ((:meta :trigger-fns (p))))
  (defattach f1 g1)
  (defattach f2 g2)
  (defthm contradiction
    nil
    :hints (("Goal" :use ((:instance (:theorem (not (p x)))
                                     (x t)))))
    :rule-classes nil)
 })

 <p>The form @('(all-attachments (w state))') evaluates to the list of all
 attachments except in two cases: @(see warrant)s, and attachments introduced
 with a non-@('nil') value of @(':skip-checks').  To obtain the attachment to a
 function symbol @('FN'), without the above restrictions and with value
 @('nil') if there is no attachment to @('FN'): @('(cdr (attachment-pair 'FN (w
 state)))').</p>

 <p>Next we discuss the @(':ATTACH') keyword.  There is rarely if ever a reason
 to specify @(':ATTACH T'), but the following (admittedly contrived) example
 shows why it may be necessary to specify @(':ATTACH NIL').  First we introduce
 three new function symbols.</p>

 @({
    (defstub f (x) t)

    (defun g (x)
      (f x))

    (encapsulate ((h (x) t))
      (local (defun h (x) (g x)))
      (defthm h-prop
        (equal (h x) (g x))))
 })

 <p>Now suppose we want to attach the function @(tsee acl2-numberp) to both
 @('f') and @('h').</p>

 @({
    (defattach (f acl2-numberp) (h acl2-numberp))
 })

 <p>Such an attempt fails, because the following constraint is generated but is
 not a theorem: @('(EQUAL (ACL2-NUMBERP X) (G X))').  Clearly we also need to
 attach to @('g') as well.</p>

 @({
    (defattach (f acl2-numberp) (h acl2-numberp) (g acl2-numberp))
 })

 <p>But this fails for a different reason, as explained by the error
 message:</p>

 @({
    ACL2 Error in ( DEFATTACH (F ACL2-NUMBERP) ...):  It is illegal to
    attach to function symbol G, because it was introduced with DEFUN.
    See :DOC defattach.
 })

 <p>That is: logically, we need to attach @('acl2-numberp') to @('g'), but we
 cannot actually attach to @('g') because it was not introduced with @(tsee
 encapsulate) (it was introduced with @(tsee defun)).  So we specify @(':ATTACH
 NIL') for the attachment to @('g'), saying that no actual attachment should be
 made to the code for @('g'), even though for logical purposes we should
 consider that @('g') has been given the indicated attachment.</p>

 @({
    (defattach (f acl2-numberp) (h acl2-numberp) (g acl2-numberp :attach nil))
 })

 <p>Finally, we can check that @('f'), @('g'), and @('h') execute as
 expected.</p>

 @({
      ACL2 !>(assert-event (and (f 3)
                         (not (f t))
                         (g 3)
                         (not (g t))
                         (h 3)
                         (not (h t))))
       :PASSED
      ACL2 !>
 })

 <p>The advanced feature, @(tsee with-global-stobj), imposes certain
 restrictions on a @('defattach') event.  You can probably ignore this point
 unless you get an error pertaining to @('with-global-stobj').  For relevant
 documentation see @(see with-global-stobj), specifically the section on
 ``Constrained Functions and Defattach''.</p>

 <p>We conclude with an example promised above, showing why it is necessary in
 general to unattach all function symbols in an existing attachment nest when
 unattaching any one of those function symbols.  Consider the following
 example.</p>

 @({
  (defstub f1 () t)
  (encapsulate ((f2 () t))
    (local (defun f2 () (f1)))
    (defthm f2=f1 (equal (f2) (f1))))
  (encapsulate ((f3 () t))
    (local (defun f3 () (f1)))
    (defthm f3=f1 (equal (f3) (f1))))
  (defun four () (declare (xargs :guard t)) 4)
  (defun five () (declare (xargs :guard t)) 5)
  (defattach (f1 four) (f2 four))
  (defattach (f1 five) (f3 five))
 })

 <p>The second @('defattach') erases the existing attachment pair
 @('<f1,four>') before installing the new attachment pairs @('<f1,five>') and
 @('<f3,five>').  After the second defattach, both @('(f1)') and @('(f3)')
 evaluate to 5.  Now suppose that the attachment pair @('<f2,four>') were not
 erased.  Then we would have @('(f1)') evaluating to 5 and @('(f2)') evaluating
 to 4, contradicting the constraint @('f2=f1').  The evaluation theory would
 thus be inconsistent, and at a more concrete level, the user might well be
 surprised by evaluation results if the code were written with the assumption
 specified in the constraint @('f2=f1').</p>")

(defxdoc defattach-system
  :parents (defattach)
  :short "Attach to built-in, system-level, constrained functions"
  :long "<p>For background on attachments, see @(see defattach).  The macro
 @('defattach-system') is a convenient way to attach to built-in functions.
 The event @('(defattach f g)') will fail if @('f') is built into ACL2.  This
 failure can be overcome by specifying top-level keyword argument @(':system-ok
 t'), for example: @('(defattach (f g) :system-ok t)').  However, rather than
 supplying this argument directly, it is recommended to use
 @('defattach-system'), which has the same syntax as @('defattach') with two
 exceptions: it adds @(':system-ok t') automatically, that is, @(':system-ok')
 is implicit; and it expands to a @(tsee local) call of @('defattach').  The
 latter is important so that the attachment does not affect system behavior
 outside a book containing the @('defattach') event.  Of course, if it is truly
 intended to affect such behavior, the argument @(':system-ok t') may be given
 directly to @('defattach'), without a surrounding use of @('local').</p>

 <p>See @(see system-attachments) for discussion of system attachments.  Also
 see @(see efficiency) for how to use attachments to modify the prover's
 behavior.</p>")

(defxdoc default
  :parents (arrays acl2-built-ins)
  :short "Return the @(':default') from the @(see header) of a 1- or
  2-dimensional array"
  :long "@({
  Example Form:
  (default 'delta1 a)

  General Form:
  (default name alist)
 })

 <p>where @('name') is an arbitrary object and @('alist') is a 1- or
 2-dimensional array.  This function returns the contents of the @(':default')
 field of the @(see header) of @('alist').  When @(tsee aref1) or @(tsee aref2)
 is used to obtain a value for an index (or index pair) not bound in
 @('alist'), the default value is returned instead.  Thus, the array @('alist')
 may be thought of as having been initialized with the default value.
 @('default') operates in virtually constant time if @('alist') is the semantic
 value of @('name').  See @(see arrays).</p>

 @(def default)")

(defxdoc default-backchain-limit
  :parents (rule-classes)
  :short "Specifying the backchain limit for a rule"
  :long "<p>See @(see backchain-limit).</p>

 <p>The initial value is @('(nil nil)').  To inspect the current value (as
 explained elsewhere; see @(see backchain-limit)):</p>

 @({
  (default-backchain-limit wrld :ts) ; for type-set reasoning
  (default-backchain-limit wrld :rewrite) ; for rewriting
 })")

(defxdoc default-defun-mode
  :parents (miscellaneous)
  :short "The default @(see defun-mode) of @(tsee defun)'d functions"
  :long "<p>When a @(tsee defun) is processed and no @(':mode') @('xarg') is
 supplied, the function @('default-defun-mode') is used.  To find the default
 @(see defun-mode) of the current ACL2 @(see world), type
 @('(default-defun-mode (w state))').  See @(see defun-mode) for a discussion
 of @(see defun-mode)s.  To change the default @(see defun-mode) of the ACL2
 @(see world), type one of the keywords @(':')@(tsee program) or @(':')@(tsee
 logic).</p>

 <p>The default ACL2 @(see prompt) displays the current default @(see
 defun-mode) by showing the character @('p') for @(':')@(tsee program) mode,
 and omitting it for @(':')@(tsee logic) mode; see @(see default-print-prompt).
 The default @(see defun-mode) may be changed using the keyword @(see command)s
 @(':')@(tsee program) and @(':')@(tsee logic), which are equivalent to the
 @(see command)s @('(program)') and @('(logic)').  Each of these names is
 documented separately: see @(see program) and see @(see logic).  The default
 @(see defun-mode) is stored in the @(see table) @(tsee acl2-defaults-table)
 and hence may also be changed by a @(tsee table) @(see command).  See @(see
 table) and also see @(see acl2-defaults-table).  Both mode-changing @(see
 command)s are @(see events).</p>

 <p>While @(see events) that change the default @(see defun-mode) are permitted
 within an @(tsee encapsulate) or the text of a book, their effects are @(tsee
 local) in scope to the duration of the encapsulation or inclusion.  For
 example, if the default @(see defun-mode) is @(':')@(tsee logic) and a book is
 included that contains the event @('(program)'), then subsequent @(see events)
 within the book are processed with the default @(see defun-mode) @(':')@(tsee
 program); but when the @(tsee include-book) event completes, the default @(see
 defun-mode) will still be @(':')@(tsee logic).  @(see Command)s that change
 the default @(see defun-mode) are not permitted inside @(tsee local)
 forms.</p>")

(defxdoc default-hints
  :parents (hints)
  :short "A list of hints added to every proof attempt"
  :long "@({
  Examples:
  ACL2 !>(default-hints (w state))
  ((computed-hint-1 clause)
   (computed-hint-2 clause stable-under-simplificationp))
 })

 <p>The value returned by this function is appended to the right of any
 explicitly provided :[hints] argument of every @(tsee defthm), @(tsee thm),
 and @(tsee defun) event, and similarly for the @(':guard-hints') argument of
 @('defun'), and, for ACL2(r), the @(':std-hints') argument.</p>

 <p>See @(see set-default-hints) for a more general discussion.  Advanced users
 only: see @(see override-hints) for an advanced variant of default hints that
 are not superseded by @(':')@(tsee hints) arguments.</p>")

(defxdoc default-hints-table
  :parents (default-hints)
  :short "A @(see table) used to provide @(see hints) for proofs"
  :long "<p>Please see @(see set-default-hints), see @(see add-default-hints),
 and see @(see remove-default-hints) for how to use this table.  For
 completeness, we mention here that under the hood, these events all update the
 @('default-hints-table') by updating its key, @('t'), for example as
 follows.</p>

 @({
  (table default-hints-table t
         '((computed-hint-1 clause)
           (computed-hint-2 clause
                            stable-under-simplificationp)))
 })

 <p>The use of default hints is explained elsewhere; see @(see
 set-default-hints).</p>

 <p>Advanced users only: see @(see override-hints) for an advanced variant of
 default hints.</p>")

(defxdoc default-print-prompt
  :parents (ld)
  :short "The default @(see prompt) printed by @(tsee ld)"
  :long "@({
  Example prompt:
  ACL2 p!s>
 })

 <p>The @(see prompt) printed by ACL2 displays the current package, followed by
 a space, followed by zero or more of the three @(see characters) as specified
 below, followed by the character @(tsee >) printed one or more times,
 reflecting the number of recursive calls of @(tsee ld).  The three @(see
 characters) in the middle are as follows:</p>

 @({
  p     ; when (default-defun-mode (w state)) is :program
  !     ; when guard checking is on
  s     ; when (ld-skip-proofsp state) is t
 })

 <p>See @(see default-defun-mode), see @(see set-guard-checking), and see @(see
 ld-skip-proofsp).</p>

 <p>Also see @(see ld-prompt) to see how to install your own @(see prompt).</p>

 <p>Here are some examples with @('ld-skip-proofsp nil').</p>

 @({
  ACL2 !>    ; logic mode with guard checking on
  ACL2 >     ; logic mode with guard checking off
  ACL2 p!>   ; program mode with guard checking on
  ACL2 p>    ; program mode with guard checking off
 })

 <p>Here are some examples with @(tsee default-defun-mode) of @(':')@(tsee
 logic).</p>

 @({
  ACL2 >     ; guard checking off, ld-skip-proofsp nil
  ACL2 s>    ; guard checking off, ld-skip-proofsp t
  ACL2 !>    ; guard checking on, ld-skip-proofsp nil
  ACL2 !s>   ; guard checking on, ld-skip-proofsp t
 })

 <p>Finally, here is the prompt in raw mode (see @(see set-raw-mode)),
 regardless of the settings above:</p>

 @({
  ACL2 P>
 })")

(defxdoc default-ruler-extenders
  :parents (rulers)
  :short "The default @(see ruler-extenders) for @(tsee defun)'d functions"
  :long "<p>When a @(tsee defun) is processed and no @(':ruler-extenders')
 @('xarg') is supplied, the function @('default-ruler-extenders') is used to
 obtain the current ruler-extenders; see @(see rulers).  To find the default
 ruler-extenders of the current ACL2 @(see world), type
 @('(default-ruler-extenders (w state))').</p>

 <p>While @(see events) that change the default ruler-extenders are permitted
 within an @(tsee encapsulate) or the text of a book, their effects are @(tsee
 local) in scope to the duration of the encapsulation or inclusion.  See @(see
 default-defun-mode) for an analogous discussion for defun-modes.</p>")

(defxdoc default-total-parallelism-work-limit
  :parents (parallel-proof)
  :short "For ACL2(p): returns the default value for global
  @('total-parallelism-work-limit')"
  :long "<p>See @(see set-total-parallelism-work-limit).</p>")

(defxdoc defaxiom
  :parents (events)
  :short "Add an axiom"
  :long "<p>WARNING: We strongly recommend that you not add axioms.  If at all
 possible you should use @(tsee defun) or @(tsee mutual-recursion) to define
 new concepts recursively or use @(tsee encapsulate) to constrain them
 constructively.  If your goal is to defer proving a formula that is, logically
 speaking, a theorem of the current theory, then consider using @(tsee
 skip-proofs) instead.  One such case is the use of a top-down style, as per
 the discussion on ``Top-Down Proof'' in Section B.1.2 of ``Computer-Aided
 Reasoning: An Approach.''  Note that adding new axioms may frequently render
 the logic inconsistent!</p>

 @({
  Example:
  (defaxiom sbar (equal t nil)
            :rule-classes nil)

  General Form:
  (defaxiom name term
           :rule-classes rule-classes)
 })

 <p>where @('name') is a new symbolic name (see @(see name)), @('term') is a
 term intended to be a new axiom, and @('rule-classes') is a legal value for
 @(':rule-classes') (see @(see rule-classes)).  The keyword argument is
 optional.  If @(':')@(tsee rule-classes) is not supplied, the list
 @('(:rewrite)') is used; if you wish the axiom to generate no rules, specify
 @(':')@(tsee rule-classes) @('nil').</p>")

(defxdoc defbadge
  :parents (apply$ acl2-built-ins)
  :short "Issue a badge for a function so @(tsee apply$) can evaluate with it"
  :long "<p>It is best to be somewhat familiar with the documentation of @(tsee
  apply$) before reading this topic.</p>

  <p>Before using @('defbadge') or a utility like @(tsee defun$) that relies on
  it:</p>

  @({
  (include-book "projects/apply/top" :dir :system)
  })

  <h3>Badges versus Warrants</h3>

  <p>It is easy to confuse @(see badge)s, which are issued by @('defbadge'),
  with @(see warrant)s, which are issued by @(tsee defwarrant).  Badges and
  warrants are necessary to ACL2's support of @(tsee apply$) because ACL2 is
  actually first-order, functions cannot be passed around as objects, ordinary
  symbols play the role of ``function objects,'' and somehow the logic must
  allow the association of a symbol with the function it names.  Furthermore,
  to insure the consistency of the logic @('apply$') is not allowed to handle
  certain functions such as the @('russell') function illustrated in @(tsee
  introduction-to-apply$).  But to determine whether a newly defined function
  is allowed to be known to @('apply$'), the ACL2 system must be able to
  determine, in some sense, all the functions reachable from it.  And finally,
  to be able to prove theorems about the application of such function names,
  the link between the symbols and the functions and the analyzed properties of
  the functions must be available to the prover in the form of axioms.
  Particularly vexing is the so-called ``@('local') problem'' which raises the
  possibility of proving a theorem about the application of a name in the
  context of a local definition of the corresponding function and then
  exporting that theorem to a context where the name is defined
  differently (see <b>Lesson 12</b> of @(see introduction-to-apply$)).</p>

  <p>Roughly speaking, badges are about syntax and warrants are about
  semantics.  The badge for a symbol is a data structure in the ACL2 system
  that records information like whether the symbol names a known ACL2 function,
  how many arguments that function takes, how many results it returns, which
  arguments are treated like function objects to be @(tsee apply$)'d, which are
  treated like expressions to be @(tsee ev$)'d, and which are treated like
  ordinary ACL2 objects to be @('car')'d, @('cdr')'d, consed, etc.  The
  warrant for a function is in fact another function (actually a 0-ary
  predicate) defined in the logic.  That predicate asserts some facts about the
  symbol.  In particular, it specifies the badge of the symbol and it
  constrains the behavior of @('apply$') on the symbol.</p>

  <p>@('Defbadge') analyzes the definition of a function and constructs the
  badge if possible.  @('Defbadge') does not affect the logic &mdash; no
  definitions or axioms are added.  @('Defbadge') can analyze both
  @(':program') mode functions and @(':logic') mode functions.
  @('Defwarrant'), on the other hand, can only analyze @(':logic') mode
  functions because it must inspect the measure used to justify the termination
  of the function and, if it is successful, it adds a @(':logic') mode
  definition of the warrant to the logic.  This definition links the symbol to
  the function via @('badge') and @('apply$') and if the warrant is a
  hypothesis of a conjecture then the prover ``knows'' about the linkage.</p>

  <p>Both @('defbadge') and @('defwarrant') affect the top-level
  read-eval-print loop because that loop treats @(':program') and @(':logic')
  functions differently so that it can (a) allow @(':program') mode terms to be
  evaluated to carry out commands such as @(tsee defun) and @(tsee defthm),
  query the world or build and test prototypes, and (b) allow @(':logic') mode
  terms to be evaluated while guaranteeing a certain correspondence with what
  can be proved.  See @(see guarantees-of-the-top-level-loop).</p>

  <h3>Requirements of @('Defbadge')</h3>

  @({
  General Form:
  (defbadge fn)
  })

  <p>where @('fn') is a defined function name in either @(':')@(tsee program)
  or @(':')@(tsee logic) mode.  This command analyzes the body of @('fn') to
  determine whether it satisfies certain stringent syntactic conditions
  discussed below.  If the conditions are not met, @('defbadge') signals an
  error.  Otherwise, it records a @(see badge) for @('fn').  Badges record the
  input and output arities of @('fn') and specify which arguments are
  ``functions'' that may be applied with @('apply$'), which are ``expressions''
  that may be evaluated with @(tsee ev$), and which are neither.  The
  conditions checked are sufficient to allow @(tsee apply$) to run the function
  safely at the top level of the ACL2 read-eval-print loop.  However, in order
  to prove anything about a call of @('apply$') on @('fn') &mdash; or even to
  evaluate such a call if @('fn') is in @(':')@(tsee logic) mode, as discussed
  above &mdash; @('fn') will need a @(see warrant) as issued by @(tsee
  defwarrant).  @('Defbadge') does not issue warrants, just badges.
  @('Defwarrant') can issue both badges and warrants.</p>

  <p>The first condition on @('fn') is that it must be a defined function
  symbol.  Since @('fn') must be defined it may not be a constrained function
  such as one introduced by @(tsee defchoose) or @(tsee encapsulate).  In
  addition, @('fn') may not be one of a very few ``blacklisted'' symbols (see
  the value of @('*blacklisted-apply$-fns*')) like @(tsee sys-call) (which
  requires a trust tag) or an @(see untouchable).  (For technical reasons,
  untouchables are disallowed even if they are on @('temp-touchable-fns'); see
  @(tsee remove-untouchable).)</p>

  <p>The other conditions depend on whether @(tsee apply$) is reachable from
  @('fn').  That is, can a call of @('fn') lead to a call of @('apply$')?  If
  @('apply$') is not reachable from @('fn'), then there are no more conditions
  on @('fn').  A badge for @('fn') is computed and stored.  We are more precise
  about ``reachability'' later.</p>

  <p>If @('apply$') is reachable from @('fn'), then there are additional
  conditions that must be checked.  First, @('fn') must not have been
  introduced with @(tsee mutual-recursion).  The current badging machinery is
  unable to enforce the syntactic restrictions for mutually-recursive cliques.
  Another restriction is that every function mentioned in the body of @('fn'),
  except @('fn') itself, must already have a badge.  Finally, @('fn') must
  respect certain conventions regarding its use of @(tsee apply$) and other
  @(see scion)s.  The basic idea of this last restriction is to make sure that
  @('apply$') is always called on a ``known'' function symbol or @(tsee lambda)
  object.  This restriction is enforced by checking the following
  conditions:</p>

  <p><i>(a)</i> It must be possible for each formal of @('fn') to be assigned
  one of three @(see ilk)s, @(':FN'), @(':EXPR'), or @('NIL'), as described
  below.  The basic idea is that a formal can be assigned ilk @(':FN') (or ilk
  @(':EXPR')) iff it is sometimes passed into a @(':FN') (or @(':EXPR')) slot
  in the body of @('fn') and is never passed into any other kind of slot.  A
  formal can be be assigned ilk @('NIL') iff it is never passed into a slot of
  ilk @(':FN') or @(':EXPR'), i.e., if it is used exclusively as an
  ``ordinary'' object.  We are more precise below.</p>

  <p><i>(b)</i> Every @(':FN') and @(':EXPR') slot of every function called in
  the body of @('fn') is occupied either by a formal of @('fn') of the same ilk
  or, in the case of calls of functions other than @('fn'), a quoted @(see
  tame) function symbol or quoted tame (preferably well-formed) @('LAMBDA')
  object.  (See @(tsee well-formed-lambda-objectp).)</p>

  <p>This completes the list of restrictions imposed by @('defbadge').</p>

  <h3>Discussion and Examples</h3>

  <p>Note that if @('apply$') is not reachable from @('fn'), the restrictions
  imposed on @('fn') are comparatively generous.  Such a @('fn') could be
  badged and warranted despite being defined mutually recursively or in terms
  of unbadged or even unbadgeable functions.  Basically, if @('fn') doesn't
  depend on @('apply$') there is no danger that some argument of @('fn') will
  be treated like a function object or an expression.</p>

  <p>After a successful @('defbadge') event for @('fn'), the function @(tsee
  badge) will return the computed badge (when executed in the top-level loop)
  and @(tsee apply$) will be able to accept the @('fn') as a functional
  argument.  Here is an annotated script.  First, carry out these two events,
  defining @('foldr') as a @(':program') mode function.</p>

  @({
  (include-book "projects/apply/top" :dir :system)

  (defun foldr (lst fn init)
    (declare (xargs :mode :program))
    (if (endp lst)
        init
        (apply$ fn
                (list (car lst)
                      (foldr (cdr lst) fn init)))))
  })

  <p>Note the @('apply$') call in the definition.  We see that @('foldr')
  treats its middle argument, @('fn'), as a function of arity 2.  We can run
  @('foldr'), even without assigning a badge to @('foldr'), as long as we
  supply a badged function symbol of arity 2 as the middle argument.  Since
  the ACL2 primitive @('cons') has a badge and has arity 2, we can use it:</p>

  @({
  ACL2 !>(foldr '(a b c) 'cons '(d e f))
  (A B C D E F)
  })

  <p>Since @('foldr') has arity 3, we can try to apply it to a list of three
  things.</p>

  @({
  (apply$ 'foldr (list '(a b c) 'cons '(d e f)))

  ACL2 Error in TOP-LEVEL:  The value of APPLY$-USERFN is not specified
  on FOLDR because FOLDR has not been badged.
  })

  <p>However, we can use @('defbadge') to compute and store the badge for
  @('foldr').  The badge says @('foldr') has input arity 3, output arity 1, and
  treats its middle argument as a function.  We can recover the badge by
  calling the function @(tsee badge).  We can successfully apply @('foldr').
  We can even use it in a @('lambda') expression that we pass as the middle
  argument to @('foldr').</p>

  @({
  ACL2 !>(defbadge foldr)

  FOLDR now has the badge (APPLY$-BADGE 3 1 NIL :FN NIL) but has no warrant.
  T

  ACL2 !>(badge 'foldr)
  (APPLY$-BADGE 3 1 NIL :FN NIL)

  ACL2 !>(apply$ 'foldr (list '(a b c) 'cons '(d e f)))
  (A B C D E F)

  ACL2 !>(foldr '((a b c) (d e) (f g h) (i j k))
                (lambda$ (x y)
                  (foldr x 'cons y))
                nil)
  (A B C D E F G H I J K)
  })

  <h3>The ``Reachability'' Test</h3>

  <p>We now clarify the test that we colloquially described above as whether
  @('apply$') is reachable from @('fn').  The actual test is whether
  @('apply$-userfn') is ancestral in @('fn').  That is, does @('fn') call
  @('apply$-userfn'), or a function that calls @('apply$-userfn'), or a
  function that calls a function that calls @('apply$-userfn'), etc.</p>

  <p>Since the only system functions that call @('apply$-userfn') are
  @('apply$'), @('ev$'), and @(see warrant)s, and since it is very unusual for
  a user-defined function to call directly @('apply$-userfn'), @('ev$'), or
  warrants, we think of this test colloquially as whether @('apply$') is
  ancestral in @('fn').</p>

  <p>The test and the onerous conditions imposed when @('apply$') is reachable
  is crucial to the soundness of the ACL2 proof theory.  We discuss this
  further in the background material for @(tsee apply$), including <a
  href='http://www.cs.utexas.edu/users/kaufmann/papers/apply/index.html'>``Limited
  Second-Order Functionality in a First-Order Setting''</a> by Matt Kaufmann
  and J Strother Moore and offer a fully fleshed out metalevel proof that
  @('apply$') and all @(':logic')-mode scions can be modeled in the comment
  titled <tt>Essay on Admitting a Model for Apply$ and the Functions that Use
  It</tt> in the ACL2 source file @('apply-raw.lisp').</p>

  <p>But badges are more concerned with syntax (and, for @(':program') mode
  functions, evaluation) than the proof theory.  Even if we convert @('foldr')
  to @(':logic') mode we cannot prove anything interesting about what happens
  when it is applied with @('apply$').  We can't even prove that @('foldr') has
  a badge or what that badge is!</p>

  @({
  ACL2 !>(verify-termination foldr)
  [Successful.  Output deleted.]
   FOLDR

  ACL2 !>(thm
           (equal (apply$ 'foldr (list x 'cons z))
                  (append x z)))
  [Unsuccessful.  Output deleted.]
  ******** FAILED ********

  ACL2 !>(thm
           (equal (badge 'foldr) '(APPLY$-BADGE 3 1 NIL :FN NIL)))
  [Unsuccessful.  Output deleted.]
  ******** FAILED ********

  })

  <p>In order to prove anything nontrivial about @('foldr')'s badge or behavior
  under @('apply$') we need the @(tsee warrant) for @('foldr').  Warrants are
  issued by @(tsee defwarrant).  If we execute (defwarrant foldr) and then
  amend the failed @('thm') commands above by adding @('(warrant foldr)') as a
  hypothesis, both amended formulas are provable.</p>

  <h3>How Ilks Are Assigned</h3>

  <p>If a formal variable (or its slot among the actuals) has an ilk of
  @(':FN') then the variable is ``used as a function'' in the sense that it
  might eventually reach the first argument of a call of @('apply$') and is
  never passed into an ``ordinary'' slot like those for @('cons').  Similarly,
  an ilk of @(':EXPR') means the variable is ``used as an expression'' and may
  eventually reach the first argument of @('ev$').  An ilk of @('NIL') means
  the variable is never used as a function or an expression.  The correctness
  of this algorithm is crucial to the safe evaluation of @('apply$') on
  user-defined function symbols.  It also is crucial to the termination
  argument justifying the consistency of the proof theory created if and when
  @('fn') is warranted.</p>

  <p>The key to the inductive correctness of the algorithm implicitly described
  below is the fact that when the ACL2 logic is being booted up the only
  function symbol with a slot of ilk @(':FN') is @('apply$') and the only
  function with a slot of ilk @(':EXPR') is @('ev$').  In both functions it is
  the first argument slot that is so distinguished.  All other ACL2 primitives
  that use @('apply$') or @('ev$'), e.g., @('collect$'), are defined,
  admissible, badged, and warranted under the same conditions user-defined
  functions are.</p>

  <p>Let <i>v </i> be the <i>i </i>th formal parameter of a defined function
  <i>fn</i>.  Then the ilk of <i>v </i> is @(':FN') iff the value of <i>v </i>
  eventually makes its way into the first argument of @('apply$'), either in
  the definition of @('fn') or in some function ancestral to (i.e., eventually
  called by) @('fn').  Another way to say this is that there is an occurrence
  of <i>v </i> in a slot of ilk @(':FN').  Furthermore, <i>v </i> is never used
  any other way: every place <i>v </i> occurs in the body of <i>fn </i> is in a
  slot of ilk @(':FN').  And finally, in every recursive call of <i>fn </i>,
  <i>v </i> is passed identically in the <i>i </i>th argument position of the
  call.  We say such a <i>v </i> is ``used (exclusively) as a function.''</p>

  <p>The <i>i </i>th formal variable <i>v </i> has ilk @(':EXPR') under
  analogous conditions except that instead of eventually getting into the first
  argument of @('apply$') it eventually gets into the first argument of
  @('ev$').  We say such a <i>v </i> is ``used (exclusively) as an
  expression.''  Note: @(tsee ev$) is the natural notion of expression
  evaluation in this context: look up the values of variables in the alist
  argument to @('ev$'), return quoted constants, and otherwise @('apply$')
  function symbols and @('LAMBDA') objects to the recursively obtained list of
  values returned by evaluating the actuals.  However, @('ev$') first checks
  that the expression is @(tsee tamep).</p>

  <p>The <i>i </i>th formal variable <i>v </i> has ilk @('NIL') if it never
  occurs in a @(':FN') slot and never occurs in an @(':EXPR') slot.  We say
  such a <i>v </i> is ``used (exclusively) as an ordinary object.''</p>")

(defxdoc defchoose
  :parents (events)
  :short "Define a Skolem (witnessing) function"
  :long "@({
  Examples:
  (defchoose choose-x-for-p1-and-p2 (x) (y z)
    (and (p1 x y z)
         (p2 x y z)))

  ; Axiom added by the event above:
  (IMPLIES (AND (P1 X Y Z) (P2 X Y Z))
           (LET ((X (CHOOSE-X-FOR-P1-AND-P2 Y Z)))
                (AND (P1 X Y Z) (P2 X Y Z))))

  (defchoose choose-x-for-p1-and-p2 x (y z) ; equivalent to the above
    (and (p1 x y z)
         (p2 x y z)))

  ; The following is as above, but strengthens the axiom added to pick a sort
  ; of canonical witness, as described below.
  (defchoose choose-x-for-p1-and-p2 x (y z)
    (and (p1 x y z)
         (p2 x y z))
    :strengthen t)

  (defchoose choose-x-and-y-for-p1-and-p2 (x y) (z)
    (and (p1 x y z)
         (p2 x y z)))

  General Form:
  (defchoose fn
             (bound-var1 ... bound-varn)
             (free-var1 ... free-vark)
             body
             :strengthen b),
 })

 <p>where @('fn') is the symbol you wish to define and is a new symbolic name
 (see @(see name)), @('(bound-var1 ... bound-varn)') is a list of distinct
 `bound' variables (see below), @('(free-var1 ... free-vark)') is the list of
 formal parameters of @('fn') and is disjoint from the bound variables, and
 @('body') is a term.  The use of @('lambda-list') keywords (such as
 @('&optional')) is not allowed.  The @(':strengthen') keyword argument is
 optional; if supplied, it must be @('t') or @('nil').</p>

 <p>The system treats @('fn') very much as though it were declared in the @(see
 signature) of an @(tsee encapsulate) event, with a single axiom exported as
 described below.  If you supply a @(':use') hint (see @(see hints)), @(':use
 fn'), it will refer to that axiom.  No rule (of class @(':')@(tsee rewrite) or
 otherwise; see @(see rule-classes)) is created for @('fn').</p>

 <p>@('Defchoose') is only executed in @(see defun-mode) @(':')@(tsee logic);
 see @(see defun-mode).  Also see @(see defun-sk).</p>

 <p>In the most common case, where there is only one bound variable, it is
 permissible to omit the enclosing parentheses on that variable.  The effect is
 the same whether or not those parentheses are omitted.  We describe this case
 first, where there is only one bound variable, and then address the other
 case.  Both cases are discussed assuming @(':strengthen') is @('nil'), which
 is the default.  We deal with the case @(':strengthen t') at the end.</p>

 <p>The effect of the form</p>

 @({
  (defchoose fn bound-var (free-var1 ... free-vark)
    body)
 })

 <p>is to introduce a new function symbol, @('fn'), with formal parameters
 @('(free-var1 ... free-vark)').  Now consider the following axiom, which
 states that @('fn') picks a value of @('bound-var') so that the body will be
 true, if such a value exists:</p>

 @({
  (1)   (implies body
                 (let ((bound-var (fn free-var1 ... free-vark)))
                   body))
 })

 <p>This axiom is ``clearly conservative'' under the conditions expressed
 above: the function @('fn') simply picks out a ``witnessing'' value of
 @('bound-var') if there is one.  For a rigorous statement and proof of this
 conservativity claim, see @(see conservativity-of-defchoose).</p>

 <p>Next consider the case that there is more than one bound variable, i.e.,
 there is more than one bound-var in the following.</p>

 @({
  (defchoose fn
             (bound-var1 ... bound-varn)
             (free-var1 ... free-vark)
             body)
 })

 <p>Then @('fn') returns a multiple value with @('n') components, and formula
 (1) above is expressed using @(tsee mv-let) as follows:</p>

 @({
  (implies body
           (mv-let (bound-var1 ... bound-varn)
                   (fn free-var1 ... free-vark)
                   body))
 })

 <p>We now discuss the case that @(':strengthen t') is supplied.  For
 simplicity we return to our simplest case, with @('defchoose') applied to
 function @('fn'), a single free variable @('y'), and a single bound variable
 @('bound-var').  The idea is that if we pick the ``smallest'' witnessing
 @('bound-var') for two different free variables @('y') and @('y1'), then
 either those two witnesses are the same, or else one is less than the other,
 in which case the smaller one is a witness for its free variable but not for
 the other.  (See comments in source function @('defchoose-constraint-extra')
 for more details.)  Below, @('body1') is the result of replacing @('y') by
 @('y1') in @('body').</p>

 @({
  (2)   (or (equal (fn y) (fn y1))
            (let ((bound-var (fn y)))
              (and body
                   (not body1)))
            (let ((bound-var (fn y1)))
              (and body1
                   (not body))))
 })

 <p>An important application of this additional axiom is to be able to define a
 ``fixing'' function that picks a canonical representative of each equivalence
 class, for a given equivalence relation.  The following events illustrate this
 point.</p>

 @({
  (encapsulate
   ((equiv (x y) t))
   (local (defun equiv (x y) (equal x y)))
   (defequiv equiv))

  (defchoose efix (x) (y)
    (equiv x y)
    :strengthen t)

  (defthm equiv-implies-equal-efix-1
    (implies (equiv y y1)
             (equal (efix y) (efix y1)))
    :hints (("Goal" :use efix))
    :rule-classes (:congruence))

  (defthm efix-fixes
    (equiv (efix x) x)
    :hints (("Goal" :use ((:instance efix (y x))))))
 })

 <p>If there is more than one bound variable, then (2) is modified in complete
 analogy to (1) to use @(tsee mv-let) in place of @(tsee let).</p>

 <p>Comment for logicians: As we point out in the documentation for @(tsee
 defun-sk), @('defchoose') is ``appropriate,'' by which we mean that it is
 conservative, even in the presence of @('epsilon-0') induction.  For a proof,
 See @(see conservativity-of-defchoose).</p>")

(defxdoc defcong
  :parents (events)
  :short "Prove @(see congruence) rule"
  :long "<p>@('Defcong') is used to prove that one @(see equivalence) relation
 preserves another in a given argument position of a given function.</p>
 @({
 Example:
 (defcong set-equal iff (memb x y) 2)

 is an abbreviation for

 (defthm set-equal-implies-iff-memb-2
   (implies (set-equal y y-equiv)
            (iff (memb x y) (memb x y-equiv)))
   :rule-classes (:congruence))
 })

 <p>See @(see congruence) and also see @(see equivalence).</p>

 @({
  General Form:
  (defcong equiv1 equiv2 term k
    :package package
    :event-name event-name
    :rule-classes rule-classes
    :instructions instructions
    :hints hints
    :otf-flg otf-flg)
 })

 <p>where @('equiv1') and @('equiv2') are known @(see equivalence) relations;
 @('term') is a call of a function @('fn'), other than @('if'), on the correct
 number of distinct variable arguments, @('(fn x1 ... xn)'); @('k') is a
 positive integer less than or equal to the arity of @('fn'); @('package'), if
 supplied, is one of @(':current'), @(':equiv1'), @(':equiv2'), @(':function')
 or @(':legacy'); @('event-name'), if supplied, is a symbol; and other
 arguments are as specified in the documentation for @(tsee defthm).  The
 @('defcong') macro expands into a call of @(tsee defthm).  The name of the
 @(tsee defthm) event is @('equiv1-implies-equiv2-fn-k'), unless an
 @(':event-name') keyword argument is supplied, in which case @('event-name')
 is used.  The package of symbols generated, such as variables and @(tsee
 defthm) names, is determined by the @('package') argument: if it is not
 supplied or its value is @(':current'), then the @(tsee current-package) is
 used; if its value is @(':equiv1') or @(':legacy'), then the package of
 @(':equiv1') is used; if its value is @(':equiv2'), then the package of
 @(':equiv2') is used; and if its value is @(':function'), then the package of
 @('fn') is used.  The term of the theorem is</p>

 @({
  (implies (equiv1 xk yk)
           (equiv2 (fn x1... xk ...xn)
                   (fn x1... yk ...xn))).
 })

 <p>The rule-class @(':')@(tsee congruence) is added to the @(tsee
 rule-classes) specified, if it is not already there.  All other arguments to
 the generated @(tsee defthm) form are as specified by the keyword arguments
 above.</p>

 <p>NOTE: In normal usage, @('defcong') can only create classic @(see
 congruence) rules, not @(see patterned-congruence) rules.  However, if @('fn')
 is a macro, it's possible for a patterned congruence rule to be generated,
 depending on what @('term') expands to.</p>

 <p>For example, the following produces a shallow patterned congruence
 rule:</p>

 @({
 (defun f (x y) (and x y))
 (defmacro g (x) `(f ,x t))
 (defcong iff equal (g x) 1)
 })")

(defxdoc defconst
  :parents (events programming)
  :short "Define a constant"
  :long "@({
  Examples:
  (defconst *my-digits* '(0 1 2 3 4 5 6 7 8 9))
  (defconst *len-my-digits* (the unsigned-byte (length *my-digits*)))

  General Form:
  (defconst name term)
 })

 <p>where @('name') is a symbol beginning and ending with the character @('*')
 and @('term') is a variable-free term that is evaluated to determine the value
 of the constant.</p>

 <p>There are two restrictions on @('term') aside from it being variable-free.
 Both restrictions relate to ancestral uses of @(tsee apply$) in @('term'), i.e.,
 uses of @('apply$') by @('term') or any function that might be called during the
 evaluation of @('term').  First, only badged primitive functions may be
 applied.  See @(see badge) for a way to obtain the complete list of badged
 primitives.  Second, @('loop$') and @('lambda$') may not be used anywhere in
 the ancestry of term.  See @('ignored-attachment') and
 @('prohibition-of-loop$-and-lambda$') for more discussion.</p>

 <p>When a constant symbol is used as a @(see term), ACL2 replaces it by its
 value; see @(see term).</p>

 <p>Note that @('defconst') uses so-called @(see safe-mode) to evaluate its
 form, in order to avoids soundness issues but with an efficiency penalty
 (perhaps increasing the evaluation time by several hundred percent).  If
 efficiency is a concern, or if for some reason you need the form to be
 evaluated without safe mode (e.g., you are an advanced system hacker using
 trust tags to traffic in raw Lisp code), consider using @(see defconsts)
 instead.  Also see @(see using-tables-efficiently) for an analogous issue with
 @(tsee table) events.</p>

<p>@('Defconst') sets the @('const') property of @('name') to the quoted value
of @('term'). This can be retrieved with @(tsee getpropc).</p>

 <p>It may be of interest to note that @('defconst') is implemented at the lisp
 level using @('defparameter'), as opposed to @('defconstant').
 (Implementation note: this is important for proper support of undoing and
 redefinition.)</p>

 <p>We close with a technical remark, perhaps of interest only who make use of
 the @(see hons-enabled) features of ACL2.  For an event of the form
 @('(defconst *C* (quote OBJ))'), i.e., @('(defconst *C* 'OBJ)'), then the
 value associated with @('*C*') is @('OBJ'); that is, the value of @('*C*') is
 @(tsee eq) to the actual object @('OBJ') occurring in the @('defconst') form.
 So for example, if @(tsee make-event) is used to generate such a @('defconst')
 event, as it is in the two books mentioned above, and @('OBJ') is a fast
 alist (see @(see fast-alists)), then the value of @('*C*') is a fast alist.
 This guarantee disappears if the term in the @('defconst') form is not a
 quoted object, i.e., if it is not of the form @('(quote OBJ)').</p>")

(defxdoc defequiv
  :parents (events)
  :short "Prove that a function is an @(see equivalence) relation"
  :long "@({
  Example:
  (defequiv set-equal)

  is an abbreviation for
  (defthm set-equal-is-an-equivalence
    (and (booleanp (set-equal x y))
         (set-equal x x)
         (implies (set-equal x y) (set-equal y x))
         (implies (and (set-equal x y)
                       (set-equal y z))
                  (set-equal x z)))
    :rule-classes (:equivalence))
 })

 <p>See @(see equivalence).</p>

 @({
  General Form:
  (defequiv equiv
    :package package
    :event-name event-name
    :rule-classes rule-classes
    :instructions instructions
    :hints hints
    :otf-flg otf-flg)
 })

 <p>where @('equiv') is a function symbol of arity 2; @('package'), if
 supplied, is one of @(':current'), @(':equiv') or @(':legacy');
 @('event-name'), if supplied, is a symbol; and all other arguments are as
 specified in the documentation for @(tsee defthm).  The @('defequiv') macro
 expands into a call of @(tsee defthm).  The name of the @(tsee defthm) is
 @('equiv-is-an-equivalence'), unless an @(':event-name') keyword argument is
 supplied, in which case @('event-name') is used.  The package of symbols
 generated, such as variables and @(tsee defthm) names, is determined by the
 @('package') argument: if it is not supplied or its value is @(':current'),
 then the @(tsee current-package) is used; if its value is @(':equiv') or
 @(':legacy') (which are treated identically), then the package of @(':equiv')
 is used.  All other arguments to the generated @(tsee defthm) form are as
 specified by the other keyword arguments above.  The rule-class @(':')@(tsee
 equivalence) is added to the @(see rule-classes) specified, if it is not
 already there.  The term generated for the @(tsee defthm) event states that
 @('equiv') is Boolean, reflexive, symmetric, and transitive. </p>")

(defxdoc defevaluator
  :parents (events)
  :short "Introduce an evaluator function"
  :long "@({
  Example:
  (defevaluator evl evl-list
    ((length x) (member-equal x y)))
 })

 <p>See @(see meta).</p>

 @({
  General Form:
  (defevaluator ev ev-list
     ((g1 x1 ... xn_1)
      ...
      (gk x1 ... xn_k))
     :namedp flg)       ; [optional keyword argument]
 })

 <p>where @('ev') and @('ev-list') are new function symbols and @('g1'), ...,
 @('gk') are old function symbols with the indicated number of formals, i.e.,
 each @('gi') has @('n_i') formals.  If the @(':namedp') keyword argument
 is provided, its value should be Boolean.  If not provided, the default
 value for @('flg') is @('nil').</p>

 <p>This function provides a convenient way to constrain @('ev') and
 @('ev-list') to be mutually-recursive evaluator functions for the symbols
 @('g1'), ..., @('gk').  Roughly speaking, an evaluator function for a fixed,
 finite set of function symbols is a restriction of the universal evaluator to
 terms composed of variables, constants, lambda expressions, and applications
 of the given functions.  However, evaluator functions are constrained rather
 than defined, so that the proof that a given metafunction is correct vis-a-vis
 a particular evaluator function can be lifted (by functional instantiation) to
 a proof that it is correct for any larger evaluator function.  See @(see meta)
 for a discussion of metafunctions.</p>

 <p>If the @(':namedp') @('flg') is @('nil') (the default) constraints have
 names of the form <i>ev</i>@('-CONSTRAINT-')<i>i</i>, e.g.,
 @('EV-CONSTRAINT-0'), @('EV-CONSTRAINT-1'), etc.  If @('flg') is non-@('nil'),
 the constraints are named more mnemonically, e.g., @('EV-OF-VARIABLE'),
 @('EV-OF-REVAPPEND-CALL'), etc.  We illustrate the @(':namedp t') names
 below.</p>

 <p>@('Defevaluator') executes an @(tsee encapsulate) after generating the
 appropriate @(tsee defun) and @(tsee defthm) events.  Perhaps the easiest way
 to understand what @('defevaluator') does is to execute the keyword
 command</p>

 @({
  :trans1 (defevaluator evl evl-list ((length x) (member-equal x y)))
 })

 <p>and inspect the output.  This trick is also useful in the rare case that
 the event fails because a hint is needed.  In that case, the output of
 @(':')@(tsee trans1) can be edited by adding hints, then submitted
 directly.</p>

 <p>Formally, @('ev') is said to be an ``evaluator function for @('g1'), ...,
 @('gk'), with mutually-recursive counterpart @('ev-list')'' iff @('ev') and
 @('ev-list') are constrained functions satisfying just the @(see constraint)s
 discussed below.</p>

 <p>@('Ev') and @('ev-list') must satisfy @(see constraint)s (0)-(7) and
 (k) below.  When @(':namedp nil') is supplied, the <i>i</i> in the generated
 constraint names are the parenthesized numbers below.  When @(':namedp t')
 is supplied, the mnemonic names are those shown in brackets below.</p>

 @({
  (0) How to ev an arbitrary function application:
      [EV-OF-FNCALL-ARGS]
      (implies (and (consp x)
                    (syntaxp (not (equal a ''nil)))
                    (not (equal (car x) 'quote)))
               (equal (ev x a)
                      (ev (cons (car x)
                                (kwote-lst (ev-list (cdr x) a)))
                          nil)))

  (1) How to ev a variable symbol:
      [EV-OF-VARIABLE]
      (implies (symbolp x)
               (equal (ev x a) (and x (cdr (assoc-equal x a)))))

  (2) How to ev a constant:
      [EV-OF-QUOTE]
      (implies (and (consp x)
                    (equal (car x) 'quote))
               (equal (ev x a) (cadr x)))

  (3) How to ev a lambda application:
      [EV-OF-LAMBDA]
      (implies (and (consp x)
                    (consp (car x)))
               (equal (ev x a)
                      (ev (caddar x)
                          (pairlis$ (cadar x)
                                    (ev-list (cdr x) a)))))

  (4) How to ev an empty argument list:
      [EV-LIST-OF-ATOM]
      (implies (not (consp x-lst))
               (equal (ev-list x-lst a)
                      nil))

  (5) How to ev a non-empty argument list:
      [EV-LIST-OF-CONS]
      (implies (consp x-lst)
               (equal (ev-list x-lst a)
                      (cons (ev (car x-lst) a)
                            (ev-list (cdr x-lst) a))))

  (6) How to ev a non-symbol atom:
      [EV-OF-NONSYMBOL-ATOM]
      (implies (and (not (consp x))
                    (not (symbolp x)))
               (equal (ev x a)
                      nil))

  (7) How to ev a cons whose car is a non-symbol atom:
      [EV-OF-BAD-FNCALL]
      (implies (and (consp x)
                    (not (consp (car x)))
                    (not (symbolp (car x))))
               (equal (ev x a)
                      nil))

  (k) For each i from 1 to k, how to ev an application of gi,
      where gi is a function symbol of n arguments:
      [EV-OF-gi-CALL]
      (implies (and (consp x)
                    (equal (car x) 'gi))
               (equal (ev x a)
                      (gi (ev x1 a)
                          ...
                          (ev xn a)))),
      where xi is the (cad...dr x) expression equivalent to (nth i x).
 })

 <p>@('Defevaluator') defines suitable witnesses for @('ev') and @('ev-list'),
 proves the theorems about them, and constrains @('ev') and @('ev-list')
 appropriately.  We expect @('defevaluator') to work without assistance from
 you, though the proofs do take some time and generate a lot of output.  The
 proofs are done in the context of a fixed theory, namely the value of the
 constant @('*defevaluator-form-base-theory*').</p>

 <p>(Aside: (3) above may seem surprising, since the bindings of @('a') are not
 included in the environment that is used to evaluate the lambda body,
 @('(caddar x)').  However, ACL2 lambda expressions are all <i>closed</i>: in
 @('(lambda (v1 ... vn) body)'), the only free variables in @('body') are among
 the @('vi').  See @(see term).)</p>

 <p>Acknowledgment: We thank Sol Swords and Jared Davis for their community
 book @('tools/defevaluator-fast.lisp'), which provided the model on which the
 current @('defevaluator') is based.  The original @('defevaluator') was very
 inefficient, e.g., taking thousands of times longer than the current one on an
 evaluator interpreting 800 function symbols.  We refactored their
 @('defevaluator-fast') (with permission) and made it the new implementation as
 of ACL2 Version_7.2.  Both implementations produce the same constraints modulo
 the naming option provided by @(':namedp').</p>")

(defxdoc defexec
  :parents (events mbe)
  :short "Attach a terminating executable function to a definition"
  :long "<p>Suppose you define a function @('(fn x)') with a @(see guard) of
 @('(good-input-p x)'), and you know that when the guard holds, the measure
 decreases on each recursive call.  Unfortunately, the definitional principle
 (see @(see defun)) ignores the guard.  For example, if the definition has the
 form</p>

 @({
  (defun fn (x)
    (declare (xargs :guard (good-input-p x)))
    (if (not-done-yet x)
        (... (fn (destr x)) ...)
      ...))
 })

 <p>then in order to admit this definition, ACL2 must prove the appropriate
 formula asserting that @('(destr x)') is ``smaller than'' @('x') under the
 assumption @('(not-done-yet x)') but without the assumption @('(good-input-p
 x)'), even if @('(not-done-yet x)') is true.  In essence, it may be necessary
 to submit instead the following definition.</p>

 @({
  (defun fn (x)
    (declare (xargs :guard (good-input-p x)))
    (if (good-input-p x)
        (if (not-done-yet x)
            (... (fn (destr x)) ...)
          ...)
      nil)
 })

 <p>But it is unfortunate that when calls of @('fn') are evaluated, for example
 when @('fn') is applied to an explicit constant during a proof, then a call of
 @('good-input-p') must now be evaluated on each recursive call.</p>

 <p>Fortunately, @('defexec') provides a way to keep the execution efficient.
 For the example above we could use the following form.</p>

 @({
  (defexec fn (x)
    (declare (xargs :guard (good-input-p x)))
    (mbe :logic (if (good-input-p x)
                    (if (not-done-yet x)
                        (... (fn (destr x)) ...)
                      ...)
                  nil)
         :exec  (if (not-done-yet x)
                    (... (fn (destr x)) ...)
                  ...)))
 })

 <p>Here ``@(tsee mbe)'' stands for ``must be equal'' and, roughly speaking,
 its call above is logically equal to the @(':logic') form but is evaluated
 using the @(':exec') form when the guard holds.  See @(see mbe).  The effect
 is thus to define @('fn') as shown in the @(tsee defun) form above, but to
 cause execution of @('fn') using the @(':exec') body.  The use of @('defexec')
 instead of @(tsee defun) in the example above causes a termination proof to be
 performed, in order to guarantee that evaluation always theoretically
 terminates, even when using the @(':exec') form for evaluation.</p>

 @({
  Example:

  ; Some of the keyword arguments in the declarations below are irrelevant or
  ; unnecessary, but they serve to illustrate their use.

  (defexec f (x)
    (declare (xargs :measure (+ 15 (acl2-count x))
                    :ruler-extenders :basic
                    :hints (("Goal" :in-theory (disable nth)))
                    :guard-hints (("Goal" :in-theory (disable last)))
                    :guard (and (integerp x) (<= 0 x) (< x 25)))
             (exec-xargs
                    :test (and (integerp x) (<= 0 x))
                    :default-value 'undef ; defaults to nil
                    :measure (nfix x)
                    :ruler-extenders :basic
                    :well-founded-relation o<))
    (mbe :logic (if (zp x)
                    1
                  (* x (f (- x 1))))
         :exec  (if (= x 0)
                    1
                  (* x (f (- x 1))))))
 })

 <p>The above example macroexpands to the following.</p>

 @({
  (ENCAPSULATE ()
   (LOCAL
    (ENCAPSULATE ()
     (SET-IGNORE-OK T)
     (SET-IRRELEVANT-FORMALS-OK T)
     (LOCAL (DEFUN F (X)
              (DECLARE
               (XARGS :VERIFY-GUARDS NIL
                      :HINTS (("Goal" :IN-THEORY (DISABLE NTH)))
                      :MEASURE (NFIX X)
                      :RULER-EXTENDERS :BASIC
                      :WELL-FOUNDED-RELATION O<))
              (IF (AND (INTEGERP X) (<= 0 X))
                  (IF (= X 0) 1 (* X (F (- X 1))))
                  'UNDEF)))
     (LOCAL (DEFTHM F-GUARD-IMPLIES-TEST
              (IMPLIES (AND (INTEGERP X) (<= 0 X) (< X 25))
                       (AND (INTEGERP X) (<= 0 X)))
              :RULE-CLASSES NIL))))
   (DEFUN F (X)
     (DECLARE (XARGS :MEASURE (+ 15 (ACL2-COUNT X))
                     :RULER-EXTENDERS :BASIC
                     :HINTS (("Goal" :IN-THEORY (DISABLE NTH)))
                     :GUARD-HINTS (("Goal" :IN-THEORY (DISABLE LAST)))
                     :GUARD (AND (INTEGERP X) (<= 0 X) (< X 25))))
     (MBE :LOGIC
          (IF (ZP X) 1 (* X (F (- X 1))))
          :EXEC
          (IF (= X 0) 1 (* X (F (- X 1)))))))
 })

 <p>Notice that in the example above, the @(':')@(tsee hints) in the @(tsee
 local) definition of @('F') are inherited from the @(':hints') in the @(tsee
 xargs) of the @('defexec') form.  We discuss such inheritance below.</p>

 <p>CAVEAT: Termination is not considered for calls of @(tsee mbe) under the
 top-level call.  Moreover, the @(':exec') part of an @(tsee mbe) call under
 the @(':logic') part of any superior @('mbe') call is completely ignored.</p>

 @({
  General Form:
  (defexec fn (var1 ... varn)
    dcl ... dcl ; optionally, also one documentation string, as for defun
    (mbe :LOGIC logic-body
         :EXEC  exec-body))
 })

 <p>where the syntax is identical to the syntax of @(tsee defun) where the body
 is a call of @('mbe'), with the exceptions described below.  Thus, @('fn') is
 the symbol you wish to define and is a new symbolic name and @('(var1
 ... varn)') is its list of formal parameters (see @(see name)).  The first
 exception is that at least one @('dcl') (i.e., @(tsee declare) form) must
 specify a @(':guard'), @('guard').  The second exception is that one of the
 @('dcl')s is allowed to contain an element of the form @('(exec-xargs ...)').
 The @('exec-xargs') form, if present, must specify a non-empty @(tsee
 keyword-value-listp) each of whose keys is one of @(':test'),
 @(':default-value'), or one of the standard @(tsee xargs) keys of
 @(':measure'), @(':ruler-extenders'), @(':well-founded-relation'), @(':hints')
 @(':stobjs'), or @(':dfs').  Any of these standard @('xargs') keys that is
 present in an @('xargs') of some @('dcl') but is not specified in the
 (possibly nonexistent) @('exec-xargs') form is considered to be specified in
 the @('exec-xargs') form, as illustrated in the example above for @(':hints').
 (So for example, if you want @(':hints') in the final, non-local definition
 but not in the local definition, then specify the @(':hints') in the
 @('xargs') but specify @(':hints nil') in the @('exec-xargs').)  If @(':test')
 is specified and not @('nil'), let @('test') be its value; otherwise let
 @('test') default to @('guard').  If @(':default-value') is specified, let
 @('default-value') be its value; else @('default-value') is @('nil').
 @('Default-value') should have the same @(see signature) as @('exec-body');
 otherwise the @('defexec') form will fail to be admitted.</p>

 <p>The above General Form's macroexpansion is of the form @('(PROGN encap
 final-def)'), where @('encap') and @('final-def') are as follows.
 @('Final-def') is simply the result of removing the @('exec-xargs')
 declaration (if any) from its @(tsee declare) form, and is the result of
 evaluating the given @('defexec') form, since @('encap') is of the following
 form.</p>

 @({
  ; encap
  (ENCAPSULATE ()
    (set-ignore-ok t)             ; harmless for proving termination
    (set-irrelevant-formals-ok t) ; harmless for proving termination
    (local local-def)
    (local local-thm))
 })

 <p>The purpose of @('encap') is to ensure that the executable version of
 @('name') terminates on all arguments.  Thus, @('local-def') and
 @('local-thm') are as follows, where the @('xargs') of the @(tsee declare)
 form are the result of adding @(':VERIFY-GUARDS NIL') to the result of
 removing the @(':test') and (optional) @(':default-value') from the
 @('exec-xargs').</p>

 @({
  ; local-def
  (DEFUN fn formals
    (DECLARE (XARGS :VERIFY-GUARDS NIL ...))
    (IF test
        exec-body
      default-value))

  ; local-thm
  (DEFTHM fn-EXEC-GUARD-HOLDS
    (IMPLIES guard test)
    :RULE-CLASSES NIL)
 })

 <p>We claim that if the above @('local-def') and @('local-thm') are admitted,
 then all evaluations of calls of @('fn') terminate.  The concern is that the
 use of @(tsee mbe) in @('final-def') allows for the use of @('exec-body') for
 a call of @('fn'), as well as for subsequent recursive calls, when @('guard')
 holds and assuming that the guards have been verified for @('final-def').
 However, by @('local-thm') we can conclude in this case that @('test') holds,
 in which case the call of @('fn') may be viewed as a call of the version of
 @('fn') defined in @('local-def').  Moreover, since guards have been verified
 for @('final-def'), then guards hold for subsequent evaluation of
 @('exec-body'), and in particular for recursive calls of @('fn'), which can
 thus continue to be viewed as calls using @('local=def').</p>")

(defxdoc definductor
  :parents (loop$-recursion)
  :short "Create an induction scheme for a @('loop$')-recursive function"
  :long "<p>@('Definductor') is a utility provided as part of the community
  book @('projects/apply/top'), which should be included in any session dealing
  with @(tsee apply$), @(tsee loop$), or @(tsee loop$-recursion).
  @('(Definductor fn)') attempts to create an induction scheme appropriate for
  the previously defined @('loop$')-recursive function @('fn') and prove an
  @(':')@(tsee induction) rule so that certain calls of @('fn') suggest that
  induction.</p>

  <p><b>Warning:</b> @('Definductor') currently handles a very small class of
  @('loop$')-recursive functions and may produce unhelpful error messages when
  given a function name outside of that class!  We hope to improve it and this
  documentation as we all get more experience with @('loop$')s and
  @('loop$')-recursion.</p>

  @({
  Examples:
  (definductor copy-nat-tree)

  (definductor copy-nat-tree
               :measure (my-measure x)
               :hints (("Goal" :use ...)))

  General Form:
  (definductor name &key measure well-founded-relation ruler-extenders hints)
  })

  <p>where @('name') is the name of a previously admitted @('loop$')-recursive
  function satisfying the restrictions listed below.  When successful it
  defines a function named @('name-INDUCTOR') that suggests an induction scheme
  that is supposedly appropriate for @('name'), admits it with a silent proof
  of its measure theorems, and then proves an @(':')@('induction') rule to
  associate that scheme with calls of @('name').  When omitted, the optional
  keyword arguments @('measure'), @('well-founded-relation'), and
  @('ruler-extenders') default to the measure, well-founded relation, and
  ruler-extender settings used in the admittance of @('name').  The keyword
  argument @('hints') defaults to @('nil').  Note that an appropriate choice of
  @('ruler-extenders') can improve some induction schemes.  See @(see
  induction-coarse-v-fine-grained).</p>

  <h3>Restrictions</h3>

  <p>The given function, @('name'), must satisfy the following restrictions.
  <b>Note:</b> Because we anticipate this utility being further developed in the
  near future this list may not correspond to the latest implementation!</p>

  <ul>

  <li>@('Name') must be a symbol naming a previously admitted @('loop$')-recursive
  function.</li>

  <li>Every recursive @('loop$') in the body of @('name') -- that is, every
  @('loop$') that calls @('name') recursively in the @('when'), @('until'), or
  @('body') clauses of the @('loop$') -- must have as its target(s) distinct
  measured variables or @('cdr')-nests around such variables.</li>

  <li>Every recursive @('loop$') must use @('IN')-iteration, not @('ON')- or
  @('FROM/TO/BY')-iteration.</li>

  </ul>

  <p>While @('definductor') can handle @('loop$') containing multiple @('AS')
  clauses (with targets as described above), it cannot handle @('loop$') such
  as</p>

  @({
  (loop$ for v in (target x) ...)
  (loop$ for v on x ...)
  (loop$ for i from 1 to max ...)
  })

  <p>To see the inductor function generated, type @(':pe name-INDUCTOR').  To
  see examples of the use of @('definductor') inspect the book
  @('projects/apply/definductor-tests.lisp').  To see the definition of
  @('definductor'), see @('projects/apply/definductor.lisp').</p>

  <p>Suggestions for improvements are welcome!  We know of many, including
  allowing the user to specify a different name for the inductor function,
  improving the error messages, printing out the generated @('defun') in the
  event of failure to admit it, and trying to expand the class of
  @('loop$')-recursive functions that can be successfully handled.  We have not
  yet even looked at inductions for @('ON') @('loop$')s and @('FROM/TO/BY')
  @('loop$')s, so that might be easy.  Induction for @('loop$')s over arbitrary
  target expressions may be infeasible!  We just need more examples of
  @('loop$')-recursive functions and successful (hand-written) induction hints
  for them.</p>")

(defxdoc define-pc-help
  :parents (proof-builder)
  :short "Define a macro command whose purpose is to print something"
  :long "@({
  Example:
  (define-pc-help pp ()
    (if (goals t)
        (io? proof-builder nil state
             (state-stack)
             (fms0 "~|~y0~|"
                   (list (cons #0
                               (fetch-term (conc t)
                                           (current-addr t))))))
      (print-all-goals-proved-message state)))

  General Form:
  (define-pc-help name args &rest body)
 })

 <p>This defines a macro command named @('name'), as explained further below.
 The @('body') should (after removing optional declarations) be a form that
 returns @('state') as its single value.  Typically, it will just print
 something.</p>

 <p>What @('(define-pc-help name args &rest body)') really does is to create a
 call of @('define-pc-macro') that defines @('name') to take arguments
 @('args'), to have the declarations indicated by all but the last form in
 @('body'), and to have a body that (via @('pprogn')) first executes the form
 in the last element of body and then returns a call to the command @('skip')
 (which will return @('(mv nil t state)')).</p>")

(defxdoc define-pc-macro
  :parents (proof-builder)
  :short "Define a proof-builder macro command"
  :long "<p>A call of @('define-pc-macro') defines a sort of macro, which is a
 tactic that generates @(see proof-builder) instructions.  This topic contains
 basic information about how to use this utility.  For somewhat sophisticated,
 but commented, examples, see the @(see community-book)
 @('books/kestrel/utilities/proof-builder-macros.lisp') and associated tests in
 the same directory, @('proof-builder-macros-tests.lisp').</p>

 <p>We begin with the following example.</p>

 @({
 (define-pc-macro ib (&optional term)
   (value
    (if term
        `(then (induct ,term) bash)
      `(then induct bash))))
 })

 <p>The example above captures a common paradigm: one attempts to prove the
 current goal by inducting and then simplifying the resulting goals.  (See
 @(see proof-builder-commands) for documentation of the command @('then'),
 which is itself a pc-macro command, and commands @('induct') and @('bash').)
 Rather than issuing @('(then induct bash)'), or worse yet issuing @('induct')
 and then issuing @('bash') for each resulting goal, the above definition of
 @('ib') would let you issue @('ib') and get the same effect.</p>

 @({
 General Form:
 (define-pc-macro cmd args dcl ... dcl body)
 })

 <p>where @('cmd') is the name of the pc-macro that you want to define,
 @('args') is its list of formal parameters.  @('Args') may include lambda-list
 keywords @('&optional') and @('&rest'); see @(see macro-args), but note that
 here, @('args') may not include @('&key') or @('&whole').</p>

 <p>The value of @('body') should be an @(see error-triple), of the form @('(mv
 erp xxx state)') for some @('erp') and @('xxx').  If @('erp') is @('nil'),
 then @('xxx') is handed off to the interactive proof-builder's instruction
 interpreter.  Otherwise, evaluation typically halts.</p>")

(defxdoc define-pc-meta
  :parents (proof-builder)
  :short "Define a proof-builder meta command"
  :long "<p>Built-in meta commands of the interactive @(see proof-builder)
 include @('undo') and @('restore'), and others (@('lisp'), @('exit'), and
 @('sequence')); see @(see proof-builder-commands).  The advanced proof-builder
 user can define these as well.  See ACL2 source file @('proof-builder-b.lisp')
 for examples, and contact the ACL2 implementors if those examples do not
 provide sufficient documentation.</p>")

(defxdoc define-trusted-clause-processor
  :parents (events)
  :short "Define a trusted (unverified) goal-level simplifier"
  :long "<p>This @(see documentation) assumes familiarity with
 @(':clause-processor') rules; see @(see clause-processor).  Briefly put, a
 <i>clause-processor</i> is a user-defined function that takes as input the
 ACL2 representation of a goal &mdash; a @(see clause) &mdash; and returns a
 list of goals (i.e., a list of clauses).  A @(':clause-processor') rule is a
 way to inform ACL2 that a clause-processor has been proved correct and now may
 be specified in @(':clause-processor') @(see hints).</p>

 <p>Here we describe a utility, @('define-trusted-clause-processor'), that
 provides another way to inform ACL2 that a function is to be considered a
 clause-processor that can be specified in a @(':clause-processor') hint.  You
 can find examples of correct and incorrect use of this utility in community
 book @('books/clause-processors/basic-examples').</p>

 <p>Consider the simple example already presented for @(':clause-processor')
 rules (again, see @(see clause-processor)), for a simple clause-processor
 named @('note-fact-clause-processor').  Instead of introducing an evaluator
 and proving a correctness theorem with @(':rule-classes :clause-processor'),
 we can simply inform ACL2 that we trust the function
 @('note-fact-clause-processor') to serve as a clause-processor.</p>

 @({
  (define-trusted-clause-processor
    note-fact-clause-processor
    nil
    :ttag my-ttag)
 })

 <p>A non-nil @(':ttag') argument generates a @(tsee defttag) event in order to
 acknowledge the dependence of the ACL2 session on the (unproved) correctness
 of this clause-processor.  That argument can be omitted if there is currently
 an active trust tag.  Note that the extra @(tsee defttag) event will be @(see
 local) to the @('define-trusted-clause-processor') event; that is, its effect
 will disappear after the @('define-trusted-clause-processor') event completes.
 This point becomes clear if one understands that a call of
 @('define-trusted-clause-processor') expands to a call of @(tsee encapsulate),
 and a @(tsee defttag) event is essentially @(see local) within any @(tsee
 encapsulate) event, as is any event that sets the @(tsee acl2-defaults-table).
 See @(see defttag).  Because we are trusting this clause-processor, rather
 than having proved it correct, we refer to it as a ``trusted''
 clause-processor to contrast with a proved-correct, or ``verified'',
 clause-processor.</p>

 <p>Now that the event displayed above has established
 @('note-fact-clause-processor') as a (trusted) clause-processor, we can use it
 in a @(':clause-processor') hint, for example as follows.  Notice that the
 output is identical to that for the corresponding example presented for the
 verified case (see @(see clause-processor)), except that the word ``verified''
 has been replaced by the word ``trusted''.</p>

 @({
  ACL2 !>(thm (equal (car (cons x y))
                     x)
              :hints
              (("Goal"
                :clause-processor
                (note-fact-clause-processor clause '(equal a a)))))

  [Note:  A hint was supplied for the goal above.  Thanks!]

  We now apply the trusted :CLAUSE-PROCESSOR function NOTE-FACT-CLAUSE-
  PROCESSOR to produce two new subgoals.

  Subgoal 2
  (IMPLIES (EQUAL A A)
           (EQUAL (CAR (CONS X Y)) X)).

  But we reduce the conjecture to T, by the :executable-counterpart of
  IF and the simple :rewrite rule CAR-CONS.

  Subgoal 1
  (EQUAL A A).

  But we reduce the conjecture to T, by primitive type reasoning.

  Q.E.D.

  Summary
  Form:  ( THM ...)
  Rules: ((:EXECUTABLE-COUNTERPART IF)
          (:EXECUTABLE-COUNTERPART NOT)
          (:FAKE-RUNE-FOR-TYPE-SET NIL)
          (:REWRITE CAR-CONS))
  Warnings:  None
  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)

  Proof succeeded.
  ACL2 !>
 })

 <p>Indeed, if one runs this example first and subsequently verifies the
 clause-processor, one will see the word ``trusted'' change to
 ``verified''.</p>

 <p>The general form is as follows.</p>

 @({
  (define-trusted-clause-processor
    cl-proc           ;;; clause-processor function
    supporters        ;;; see below
    &key
    label             ;;; optional; cl-proc$label by default
    ttag              ;;; discussed above
    partial-theory    ;;; optional encapsulate event
    )
 })

 <p>We discussed the @(':ttag') argument above, and we will discuss the
 @('supporters') and @(':partial-theory') arguments later below.  Let us turn
 our attention to the @('label') argument and its ramifications for undoing and
 redundancy.</p>

 <p>As mentioned above, a successful @('define-trusted-clause-processor') event
 results in an @(tsee encapsulate) event.  If the @(':label') argument is
 supplied with a non-@('nil') value @('L'), or if @(':label') is omitted and
 @('L') is the result of adding the suffix @('"$LABEL"') to @('cl-proc'),
 then the event @('(deflabel L)') will be included under the resulting
 @('encapsulate') form.  Thus, you will be able to undo this
 @('define-trusted-clause-processor') with @(':')@(tsee ubt)@(' L').  Also,
 because of the criteria for redundant encapsulate events (see @(see
 REDUNDANT-ENCAPSULATE)), the entire form is considered redundant (skipped) if
 it is identical to one already executed in the current ACL2 @(see world), with
 one exception: if @(':partial-theory') is @('nil') or omitted, and also
 @(':label nil') is supplied explicitly, then the event will not be redundant.
 If the event is not redundant, then @('cl-proc') must not already be
 designated as a trusted clause-processor.</p>

 <p>Note that @('cl-proc') may be defined either in @(':program')-mode or
 @(':logic')-mode.</p>

 <p>The @('supporters') argument should be a true list of function symbols in
 the current ACL2 world.  It is important that this list include user-defined
 functions whose definitions support the correctness of the clause-processor
 function.  Otherwise, @(tsee local) definitions of those missing supporters
 can render the use of this clause-processor unsound, as discussed in the paper
 referenced at the end of the @(see clause-processor) documentation topic.
 Below we discuss an additional reason that @('supporters') is critical for
 soundness, in the case of dependent clause-processors.</p>

 <p>(Remark.  There could have been two notions of supporters: one for
 functions whose definitions support the correctness of the clause-processor
 function, and, in the case of dependent clause-processors, one for supporters
 of the ``promised encapsulate'' discussed below.  But for simplicity, a single
 @('supporters') argument serves both purposes.)</p>

 <p><b>Dependent clause-processors and promised encapsulates</b>: The
 @(':partial-theory') argument</p>

 <p>Suppose you want to introduce a clause-processor to reason about a complex
 hardware simulator that is implemented outside ACL2.  Sawada and Reeber had
 just such a problem, as reported in their FMCAD 2006 paper.  Indeed, they used
 @(tsee sys-call) to implement a @(':')@(tsee program)-mode function in ACL2
 that can invoke that simulator.  (This has been changed to @(tsee sys-call*)
 since @('sys-call') cannot invoke the OS during proofs; see @(see sys-call).)
 In principle one could code the simulator directly in ACL2; but it would be a
 tremendous amount of work that has no practical purpose, given the interface
 to the external simulator.  So: In what sense can we have a clause-processor
 that proves properties about a simulator when that simulator is not fully
 axiomatized in ACL2?  Our answer, in a nutshell, is this: The above
 @(':partial-theory') argument provides a way to write merely some of the @(see
 constraint)s on the external tool (or even no constraints at all), with the
 understanding that such constraints are present implicitly in a stronger
 ``promised'' @('encapsulate'), for example by exporting the full
 definition.</p>

 <p>If a trusted clause-processor is introduced with a non-@('nil')
 @(':partial-theory') argument, we call it a ``dependent'' clause-processor,
 because its correctness is dependent on the constraints implicitly introduced
 by the @(':partial-theory') @('encapsulate') form.  The implicit constraints
 should logically imply the constraints actually introduced by the explicit
 @('encapsulate'), but they should also be sufficient to justify every possible
 invocation of the clause-processor in a @(':clause-processor') hint.  The user
 of a @('define-trusted-clause-processor') form is making a guarantee &mdash;
 or, is relying on a guarantee provided by the writer of that form &mdash; that
 in principle, there exists a so-called ``promised encapsulate'': an
 @('encapsulate') form with the same @(see signature) as the
 @(':partial-theory') @('encapsulate') form associated with the trusted
 clause-processor, but whose constraints introduced are the aforementioned
 implicit constraints.</p>

 <p>There are several additional requirements on a @(':partial-theory')
 argument.  First, it must be an @(tsee encapsulate) event with non-empty @(see
 signature).  Moreover, the functions introduced by that event must be exactly
 those specified in the signature, and no more.  And further still, the
 @('define-trusted-clause-processor') form cannot be executed inside any @(tsee
 encapsulate) form with non-empty @(see signature); we can think of this
 situation as attempting to associate more than one @('encapsulate') with the
 functions introduced in the inner @('encapsulate').</p>

 <p>Moreover, soundness depends on inclusion of enough function symbols in the
 @('supporters') argument, as follows.  Let @('S') be the set of specified
 @('supporters') augmented by the set of function symbols either introduced by,
 or in a property exported by, the @(':partial-theory') argument, which we call
 the ``promised encapsulate''.  Then every function symbol constrained by the
 promised encapsulate is in @('S').</p>

 <p>The @(':partial-theory') event will (in essence) be executed as part of the
 evaluation of the @('define-trusted-clause-processor') form.  Again, a
 critical obligation rests on the user who provides a @(':partial-theory'):
 there must exist (in principle at least) a corresponding promised encapsulate
 form with the same @(see signature) that could logically be admitted, whenever
 the above @('define-trusted-clause-processor') form is evaluated successfully,
 that justifies the designation of @('cl-proc') as a clause-processor.  See
 also the paper mentioned above for more about promised encapsulates.  A key
 consequence is that the @(see constraint)s are unknown for the functions
 introduced in (the signature of) a @(':partial-theory') @(tsee encapsulate)
 form.  Thus, functional instantiation (see @(see
 functional-instantiation-example)) is disabled for function in the signature
 of a @(':partial-theory') form.</p>

 <p><b>A remark on the underlying implementation</b></p>

 <p>You can see all of the current trusted clause-processors by issuing the
 command @('(table trusted-cl-proc-table)').  The resulting alist associates
 each trusted clause-processor with its supporters.</p>

 <p>Note that @('define-trusted-clause-processor') is actually a macro that
 generates (among other things) a @('table') event for extending
 @('trusted-cl-proc-table').  You are invited to use @(':')@(tsee trans1) to
 see expansions of calls of this macro.  In particular, you can see that the
 @(':partial-theory') argument results in an @('encapsulate') event that
 includes a call of the form @('(set-unknown-constraints-supporters f1
 ... fk)'), which in effect makes that call of @('encapsulate') into a call of
 @('partial-encapsulate') with supporters @('(f1 ... fk)').  See @(see
 partial-encapsulate).</p>

 <p><b>A technique for using raw Lisp to define a trusted
 clause-processor</b></p>

 <p>The following code is intended to give an idea for how one might define the
 ``guts'' of a trusted clause-processor in raw Lisp.  The idea is to stub out
 functions, such as @('acl2-my-prove below'), that you want to define in raw
 Lisp; and then, load a raw Lisp file to overwrite any such function with the
 real code.  But then we make any such overwritten function untouchable.  (This
 last step is important because otherwise, one can prove @('nil') using a
 @(':functional-instance') @(':use') hint, by exploiting the fact that this
 function has executable code for which there is no corresponding definitional
 axiom.)  Note: The point here is only to illustrate the use of raw Lisp, so we
 do not bother to define or explain functions @('hint-to-termlist') or
 @('disjoin-clause-segments-to-clause'), which this example assumes are defined
 elsewhere; their meanings are not important for this example.</p>

 @({
  (defstub acl2-my-prove (term hint) t)

  (program)

  (defttag :my-cl-proc)

  (progn

  ; We wrap everything here in a single progn, so that the entire form is
  ; atomic.  That's important because we want the use of push-untouchable to
  ; prevent anything besides my-clause-processor from calling acl2-my-prove.

    (progn!

     (set-raw-mode-on state)

     (load "my-hint-raw.lsp") ; defines my-prove in raw Lisp

     (defun acl2-my-prove (term hint)
       (my-prove term hint)))

    (defun my-clause-processor (cl hint)
      (declare (xargs :guard (pseudo-term-listp cl)
                      :mode :program))
      (if (acl2-my-prove (disjoin cl) hint)
          (disjoin-clause-segments-to-clause
           (pairlis$ (hint-to-termlist hint) nil)
           cl)
        (prog2$ (cw "~|~%NOTE: Unable to prove goal with ~
                    my-clause-processor and indicated hint.~|")
                (list cl))))

    (push-untouchable acl2-my-prove t)
    )
 })")

(defxdoc definition
  :parents (rule-classes)
  :short "Make a rule that acts like a function definition"
  :long "<p>See @(see rule-classes) for a general discussion of rule classes
 and how they are used to build rules from formulas.  An example @(':')@(tsee
 corollary) formula from which a @(':definition') rule might be built is:</p>

 @({
  Examples:
  (defthm open-len-twice
    (implies (true-listp x)
             (equal (len x)
                    (if (null x)
                        0
                      (if (null (cdr x))
                          1
                        (+ 2 (len (cddr x)))))))
    :rule-classes :definition)

  ; Same as above, with :controller-alist made explicit:
  (defthm open-len-twice
    (implies (true-listp x)
             (equal (len x)
                    (if (null x)
                        0
                      (if (null (cdr x))
                          1
                        (+ 2 (len (cddr x)))))))
    :rule-classes ((:definition :controller-alist ((len t)))))

  General Form:
  (implies hyp (equiv (fn a1 ... an) body))
 })

 <p>where @('equiv') is an equivalence relation and @('fn') is a function
 symbol other than @(tsee if), @(tsee hide), @(tsee force) or @(tsee
 case-split).  Such rules allow ``alternative'' definitions of @('fn') to be
 proved as theorems but used as definitions.  These rules are not true
 ``definitions'' in the sense that they (a) cannot introduce new function
 symbols and (b) do not have to be terminating recursion schemes.  They are
 just conditional rewrite rules that are controlled the same way we control
 recursive definitions.  We call these ``definition rules'' or ``generalized
 definitions''.</p>

 <p>Consider the general form above.  Generalized definitions are stored much
 as @(':')@(tsee rewrite) rules for the function ``defined,'' @('fn') above,
 but the procedure for applying them is a little different.  During rewriting,
 instances of @('(fn a1 ... an)') are replaced by corresponding instances of
 @('body') provided the @('hyp')s can be established, as for a @(':')@(tsee
 rewrite) rule; but when applying a @(':definition') rule, the result of
 rewriting @('body') must also satisfy the criteria for function expansion.
 There are two primary criteria, either of which permits expansion.  The first
 is that the ``recursive'' calls of @('fn') in the rewritten body have
 arguments that already occur in the goal conjecture.  The second is that the
 ``controlling'' arguments to @('fn') are simpler in the rewritten body.</p>

 <p>The notions of ``recursive call'' and ``controllers'' are complicated by
 the provisions for mutually recursive definitions.  Consider a ``clique'' of
 mutually recursive definitions.  Then a ``recursive call'' is a call to any
 function defined in the clique and an argument is a ``controller'' if it is
 involved in the measure that decreases in all recursive calls.  These notions
 are precisely defined by the definitional principle and do not necessarily
 make sense in the context of generalized definitional equations as implemented
 here.</p>

 <p>But because the heuristics governing the use of generalized definitions
 require these notions, it is generally up to the user to specify which calls
 in body are to be considered recursive and what the controlling arguments are.
 This information is specified in the @(':clique') and @(':controller-alist')
 fields of the @(':definition') rule class.</p>

 <p>The @(':clique') field is the list of function symbols to be considered
 recursive calls of @('fn').  In the case of a non-recursive definition, the
 @(':clique') field is empty; in a singly recursive definition, it should
 consist of the singleton list containing @('fn'); otherwise it should be a
 list of all of the functions in the mutually recursive clique with this
 definition of @('fn').</p>

 <p>If the @(':clique') field is not provided it defaults to @('nil') if
 @('fn') does not occur as a function symbol in @('body') and it defaults to
 the singleton list containing @('fn') otherwise.  Thus, @(':clique') must be
 supplied by the user only when the generalized definition rule is to be
 treated as one of several in a mutually recursive clique.</p>

 <p>The @(':controller-alist') is an alist that maps each function symbol in
 the @(':clique') to a mask specifying which arguments are considered
 controllers.  The mask for a given member of the clique, @('fn'), must be a
 list of @('t')'s and @('nil')'s of length equal to the arity of @('fn').  A
 @('t') should be in each argument position that is considered a ``controller''
 of the recursion.  For a function admitted under the principle of definition,
 an argument controls the recursion if it is one of the arguments measured in
 the termination argument for the function.  But in generalized definition
 rules, the user is free to designate any subset of the arguments as
 controllers.  Failure to choose wisely may result in the ``infinite
 expansion'' of definitional rules but cannot render ACL2 unsound since the
 rule being misused is a theorem.</p>

 <p>If the @(':controller-alist') is omitted it can sometimes be defaulted
 automatically by the system.  If the @(':clique') is @('nil'), the
 @(':controller-alist') defaults to @('nil').  If the @(':clique') is a
 singleton containing @('fn'), the @(':controller-alist') defaults to the
 controller alist computed by @('(defun fn args body)').  (The user can obtain
 some control over this analysis by setting the default ruler-extenders; see
 @(see rulers).)  If the @(':clique') contains more than one function, the user
 must supply the @(':controller-alist') specifying the controllers for each
 function in the clique.  This is necessary since the system cannot determine
 and thus cannot analyze the other definitional equations to be included in the
 clique.</p>

 <p>For example, suppose @('fn1') and @('fn2') have been defined one way and it
 is desired to make ``alternative'' mutually recursive definitions available to
 the rewriter.  Then one would prove two theorems and store each as a
 @(':definition') rule.  These two theorems would exhibit equations
 ``defining'' @('fn1') and @('fn2') in terms of each other.  No provision is
 here made for exhibiting these two equations as a system of equations.  One is
 proved and then the other.  It just so happens that the user intends them to
 be treated as mutually recursive definitions.  To achieve this end, both
 @(':definition') rules should specify the @(':clique') @('(fn1 fn2)') and
 should specify a suitable @(':controller-alist').  If, for example, the new
 definition of @('fn1') is controlled by its first argument and the new
 definition of @('fn2') is controlled by its second and third (and they each
 take three arguments) then a suitable @(':controller-alist') would be @('((fn1
 t nil nil) (fn2 nil t t))').  The order of the pairs in the alist is
 unimportant, but there must be a pair for each function in the clique.</p>

 <p>Inappropriate heuristic advice via @(':clique') and @(':controller-alist')
 can cause ``infinite expansion'' of generalized definitions, but cannot render
 ACL2 unsound.</p>

 <p>Note that the actual definition of @('fn1') has the runic name
 @('(:definition fn1)').  The runic name of the alternative definition is
 @('(:definition lemma)'), where @('lemma') is the name given to the event that
 created the generalized @(':definition') rule.  This allows theories to switch
 between various ``definitions'' of the functions.</p>

 <p>By default, a @(':definition') rule establishes the so-called ``body'' of a
 function.  The body is used by @(':expand') @(see hints), and it is also used
 heuristically by the theorem prover's preprocessing (the initial
 simplification using ``simple'' rules that is controlled by the
 @('preprocess') symbol in @(':do-not') @(see hints)), induction analysis, and
 the determination for when to warn about non-recursive functions in rules.
 The body is also used by some heuristics involving whether a function is
 recursively defined, and by the @('expand'), @('x'), and @('x-dumb') commands
 of the interactive @(see proof-builder).</p>

 <p>See @(see rule-classes) for a discussion of the optional field
 @(':install-body') of @(':definition') rules, which controls whether a
 @(':definition') rule is used as described in the paragraph above.  Note that
 even if @(':install-body nil') is supplied, the rewriter will still rewrite
 with the @(':definition') rule; in that case, ACL2 just won't install a new
 body for the top function symbol of the left-hand side of the rule, which for
 example affects the application of @(':expand') hints as described in the
 preceding paragraph.  Also see @(see set-body) and see @(see show-bodies) for
 how to change the body of a function symbol.</p>

 <p>Note only that if you prove a definition rule for function @('foo'), say,
 @('foo-new-def'), you will need to refer to that definition as
 @('foo-new-def') or as @('(:DEFINITION foo-new-def)').  That is because a
 @(':definition') rule does not change the meaning of the symbol @('foo') for
 @(':use') @(see hints), nor does it change the meaning of the symbol @('foo')
 in theory expressions; see @(see theories), in particular the discussion there
 of runic designators.  Similarly @(':')@(tsee pe) @('foo') and @(':')@(tsee
 pf) @('foo') will still show the original definition of @('foo').</p>

 <p>The definitional principle, @(tsee defun), actually adds @(':definition')
 rules.  Thus the handling of generalized definitions is exactly the same as
 for ``real'' definitions because no distinction is made in the implementation.
 Suppose @('(fn x y)') is @(tsee defun)'d to be @('body').  Note that @(tsee
 defun) (or @(tsee defuns) or @(tsee mutual-recursion)) can compute the clique
 for @('fn') from the syntactic presentation and it can compute the controllers
 from the termination analysis.  Provided the definition is admissible, @(tsee
 defun) adds the @(':definition') rule @('(equal (fn x y) body)').</p>")

(defxdoc deflabel
  :parents (events)
  :short "Build a landmark"
  :long "@({
 Examples:
 (deflabel interp-section)

 General Form:
 (deflabel name)
 })

 <p>where @('name') is a new symbolic name (see @(see name)).  By virtue of the
 fact that @('deflabel') is an event, it marks the current @(see history) with
 the @('name').  For example, you may wish to undo back through some label or
 compute a theory expression (see @(see theories)) in terms of some labels.
 @('Deflabel') @(see events) are never considered redundant.  See @(see
 redundant-events).</p>")

(defxdoc deflock
  :parents (parallel-programming)
  :short "Define a wrapper macro that provides mutual exclusion in ACL2(p)"
  :long "<p>This @(see documentation) topic relates to the experimental
 extension of ACL2 supporting parallel evaluation and proof; see @(see
 parallelism).</p>

 @({
  Example Form:
  (deflock *my-lock*)

  General Form:
  (deflock *symbol*)
 })

 <p>where @('*symbol*') is a symbol whose first and last characters are both
 the character @('#\*').</p>

 <p>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 @(see guard)-verified functions, for @(':')@(tsee program) mode functions,
 and for calls of macro @(tsee top-level).  (See @(see guard-evaluation-table)
 for details of how raw Lisp code might not be invoked when guard-checking (see
 @(see set-guard-checking)) has value @(':none') or @(':all').)  Note that this
 macro is also simply the identity when invoked directly in the top-level loop;
 see @(see top-level) for a way to avoid this issue, and see @(see
 parallelism-at-the-top-level) for a general discussion of this issue for calls
 of @(see parallelism) primitives.</p>

 <p>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.</p>

 <p>Note that a call of @('deflock') expands into the application of @('progn')
 to two events, as illustrated below.</p>

 @({
  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 !>
 })

 <p>Thus, @('deflock') forms are legal embedded event forms (see @(see
 embedded-event-form)) for @(see books) as well as @(tsee encapsulate) and
 @(tsee progn) @(see events).</p>

 <p>The following log shows a lock in action.  Recall that locks work as
 expected in @(see guard)-verified and @(':')@(tsee program) mode functions;
 they do not, however, work in @(':')@(tsee logic) mode functions that have not
 been guard-verified, as illustrated below.</p>

 @({
  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 !>
 })")

(defxdoc defmacro
  :parents (macros events programming)
  :short "Define a macro"
  :long "@({
  Example Defmacros:
  (defmacro xor (x y)
    (list 'if x (list 'not y) y))

  (defmacro git (sym key)
    (list 'getprop sym key nil
          '(quote current-acl2-world)
          '(w state)))

  (defmacro one-of (x &rest rst)
    (declare (xargs :guard (symbol-listp rst)))
    (cond ((null rst) nil)
          (t (list 'or
                   (list 'eq x (list 'quote (car rst)))
                   (list* 'one-of x (cdr rst))))))

  Example Expansions:
  term                    macroexpansion

  (xor a b)              (if a (not b) b)
  (xor a (foo b))        (if a (not (foo b)) (foo b))

  (git 'car 'lemmas)     (getprop 'car 'lemmas nil
                                  'current-acl2-world
                                  (w state))

  (one-of x a b c)       (or (eq x 'a)
                             (or (eq x 'b)
                                 (or (eq x 'c) nil)))

  (one-of x 1 2 3)       ill-formed (guard violation)

  General Form:
  (defmacro name macro-args
    dcl ... dcl ; optionally, also one documentation string; see below
    body)
 })

 <p>where @('name') is a new symbolic name (see @(see name)), @('macro-args')
 specifies the formal parameters of the macro, and @('body') is a term whose
 only free variables are the @('macro-args').  The formal parameters can be
 specified in a much more general way than is allowed by ACL2 @(tsee defun)
 @(see events); see @(see macro-args) for a description of keyword (@('&key'))
 and optional (@('&optional')) parameters as well as other so-called
 ``lambda-list keywords'', @('&rest') and @('&whole').  Each @('dcl') is an
 optional declaration (see @(see declare)) except that the only @(tsee xargs)
 keyword permitted by @('defmacro') is @(':')@(tsee guard).</p>

 <p>One documentation string may be included between the list of formal
 parameters and the body, but it is essentially ignored by ACL2.  See @(see
 documentation) for a discussion of documentation in ACL2.</p>

 <p>There are two restrictions on @('body') aside from it simply being a term
 in @('macro-args').  Both restrictions relate to ancestral uses of @(tsee
 apply$) in @('body'), i.e., uses of @('apply$') by @('body') or any function
 that might be called during the evaluation of @('body').  First, only badged
 primitive functions may be applied.  See @(see badge) for a way to obtain the
 complete list of badged primitives.  Second, @('loop$') and @('lambda$') may
 not be used anywhere in the ancestry of @('body').  See
 @('ignored-attachment') and @('prohibition-of-loop$-and-lambda$') for more
 discussion.  Note: It is permitted for the value of body to mention
 @('apply$'), @('loop$'), and @('lambda$').</p>

 <p>For compute-intensive applications, see @(see defmac), which can speed up
 macroexpansion by introducing an auxiliary @('defun').  For a variant of
 @('defmacro') that automatically quotes arguments by default, but provides a
 way for calls to evaluate specified arguments, see @(see defmacroq).</p>

 <p>Macroexpansion occurs when a form is read in, i.e., before the evaluation
 or proof of that form is undertaken.  To experiment with macroexpansion, see
 @(see trans).  When a form whose @(tsee car) is @('name') arises as the form
 is read in, the arguments are bound as described in CLTL pp. 60 and 145, the
 @(see guard) is checked, and then the @('body') is evaluated.  The result is
 used in place of the original form.</p>

 <p>In ACL2, macros do not have access to the ACL2 state, @(tsee state).  (If
 @(tsee state) or any user-defined stobj (see @(see stobj)) is a macro
 argument, it is treated as an ordinary variable, bound at macro-expansion time
 to a piece of syntax.)  This is in part a reflection of CLTL, p. 143, ``More
 generally, an implementation of Common Lisp has great latitude in deciding
 exactly when to expand macro calls with a program. ...  Macros should be
 written in such a way as to depend as little as possible on the execution
 environment to produce a correct expansion.''  In ACL2, the product of
 macroexpansion is independent of the current environment and is determined
 entirely by the macro body and the functions and constants it references.  It
 is possible, however, to define macros that produce expansions that refer to
 @(tsee state) or other single-threaded objects (see @(see stobj)) or variables
 not among the macro's arguments.  See the @('git') example above.  For a
 related utility that does have access to the ACL2 @(see state), see @(see
 make-event).</p>")

(defxdoc defmacro-last
  :parents (events)
  :short "Define a macro that returns its last argument, but with side effects"
  :long "<p>This is an advanced feature that requires a trust tag.  For
 explanation, including an example, see @(see return-last).</p>")

(defxdoc defmacro-untouchable
  :parents (macros events programming defmacro)
  :short "Define an ``untouchable'' macro"
  :long "<p>Strictly speaking, macros cannot be untouchable the way functions
 are untouchable; see @(see push-untouchable).  However, one can define a macro
 that is, in effect, untouchable, by using @('defmacro-untouchable') to
 introduce a trivial untouchable function into the definition.  Consider for
 example the following definition.</p>

 @({
 (defmacro-untouchable mac (x)
   (list 'consp x))
 })

 <p>Let's look at the single-step macroexpansion of a call of the newly-defined
 macro, @('mac').</p>

 @({
 ACL2 !>:trans1 (mac (f a))
  (PROG2$ (UNTOUCHABLE-MARKER 'MAC)
          (CONSP (F A)))
 ACL2 !>
 })

 <p>We see that this expansion is just as if we had used @(tsee defmacro)
 instead of @('defmacro-untouchable'), except that a @(tsee prog2$) wrapper
 lays down a call of @('untouchable-marker'), which is a built-in untouchable
 function.  In effect, that call makes the macro, @('mac'), untouchable.</p>

 <p>Of course, you are welcome to write your own variant of
 @('defmacro-untouchable'), introducing your own untouchable function.  The
 result would presumably be roughly equivalent to using
 @('defmacro-untouchable'); but using @('defmacro-untouchable') has two
 advantages.  One advantage is that calls of a macro introduced with
 @('defmacro-untouchable') should have no Lisp execution overhead caused by the
 use of @(tsee prog2$) or @('untouchable-marker'), because of special handling
 provided by ACL2 for such calls of @('prog2$') as well as inlining of
 @('untouchable-marker').  The other advantage is that an attempt to use the
 resulting macro without an active trust tag will generally give a more helpful
 error message, mentioning the prior use of @('defmacro-untouchable') as the
 source of the error.</p>")

(defxdoc defn
  :parents (defun events)
  :short "Definition with @(see guard) @('t')"
  :long "<p>@('Defn') is @(tsee defun) with @(see guard) @('t').</p>

 <p>@('defn') expands to a @(tsee defun) with an added
 @('(declare (xargs :guard t))').  If an explicit guard is supplied to
 @('defn'), it is conjoined to the added @('t') guard, according to @(tsee
 defun)'s treatment of multiple guard declarations.</p>")

(defxdoc defnd
  :parents (defun events)
  :short "@(see disable)d definition with @(see guard) @('t')"
  :long "<p>@('Defnd') is @(tsee defund) with @(see guard) @('t').</p>

 <p>@('defnd') expands to a @(tsee defund) with an added
 @('(declare (xargs :guard t))').  If an explicit guard is supplied to
 @('defnd'), it is conjoined to the added @('t') guard, according to @(tsee
 defun)'s treatment of multiple guard declarations.</p>")

(defxdoc defpkg
  :parents (events packages programming)
  :short "Define a new symbol package"
  :long "@({
  Example:
  (defpkg "MY-PKG"
          (union-eq *acl2-exports*
                    *common-lisp-symbols-from-main-lisp-package*))

  General Form:
  (defpkg "name" term doc-string)
 })

 <p>where @('"name"') is a non-empty string, none of whose characters is
 lower case, that names the package to be created; @('term') is a variable-free
 expression that evaluates to a list of symbols, where no two distinct symbols
 in the list may have the same @(tsee symbol-name), to be imported into the
 newly created package; and @('doc-string'), if non-@('nil'), is an optional
 string that can provide documentation but is essentially ignored by ACL2.  The
 name of the new package must be ``new'': the host lisp must not contain any
 package of that name.  There are two exceptions to this newness rule,
 discussed at the end of this documentation.</p>

 <p>(There is actually an additional argument, book-path, that is used for
 error reporting but has no logical content.  Users should generally ignore
 this argument, as well as the rest of this sentence: a book-path will be
 specified for @(tsee defpkg) events added by ACL2 to the @(see portcullis) of
 a book's @(see certificate); see @(see hidden-death-package).)</p>

 <p>There are two restrictions on @('term') aside from those mentioned above.
 Both restrictions relate to ancestral uses of @(tsee apply$) in @('term'),
 i.e., uses of @('apply$') by @('term') or any function that might be called
 during the evaluation of @('term').  First, only badged primitive functions
 may be applied.  See @(see badge) for a way to obtain the complete list of
 badged primitives.  Second, @('loop$') and @('lambda$') may not be used
 anywhere in the ancestry of term.  See @('ignored-attachment') and
 @('prohibition-of-loop$-and-lambda$') for more discussion.</p>

 <p>@('Defpkg') forms can be entered at the top-level of the ACL2 @(see
 command) loop.  They should not occur in @(see books) (see @(see
 certify-book)).</p>

 <p>After a successful @('defpkg') it is possible to ``intern'' a string into
 the package using @(tsee intern-in-package-of-symbol).  The result is a symbol
 that is in the indicated package, provided the imports allow it.  For example,
 suppose @(''my-pkg::abc') is a symbol whose @(tsee symbol-package-name) is
 @('"MY-PKG"').  Suppose further that the imports specified in the
 @('defpkg') for @('"MY-PKG"') do not include a symbol whose @(tsee
 symbol-name) is @('"XYZ"').  Then</p>

 @({
  (intern-in-package-of-symbol "XYZ" 'my-pkg::abc)
 })

 <p>returns a symbol whose @(tsee symbol-name) is @('"XYZ"') and whose @(tsee
 symbol-package-name) is @('"MY-PKG"').  On the other hand, if the imports to
 the @('defpkg') does include a symbol with the name @('"XYZ"'), say in the
 package @('"LISP"'), then</p>

 @({
  (intern-in-package-of-symbol "XYZ" 'my-pkg::abc)
 })

 <p>returns that symbol (which is uniquely determined by the restriction on the
 imports list above).  See @(see intern-in-package-of-symbol).</p>

 <p>Upon admission of a @('defpkg') event, the function @('pkg-imports') is
 extended to compute a list of all symbols imported into the given package,
 without duplicates.  If @('"MY-PKG"') is the name of the new package and
 @('symb') is the symbol returned by @('(intern (concatenate 'string "MY-PKG"
 "-PACKAGE") "ACL2")'), then @('symb') denotes the @(see rewrite) rule
 added for the package.  For example, here is a display of that rule for the
 event @('(defpkg "MY-PKG" '(a b))').</p>

 @({
 ACL2 !>:pl (pkg-imports "MY-PKG")

 (:REWRITE MY-PKG-PACKAGE)
   New term: '(A B)
   Hypotheses: <none>
   Equiv: EQUAL
   Substitution: NIL

 ....
 })

 <p>@('Defpkg') is the only means by which an ACL2 user can create a new
 package or specify what it imports.  That is, ACL2 does not support the Common
 Lisp functions @('make-package') or @('import').  Currently, ACL2 does not
 support exporting at all.</p>

 <p>The Common Lisp function @(tsee intern) is weakly supported by ACL2; see
 @(see intern).  A more general form of that function is also provided: see
 @(see intern$).</p>

 <p>We now explain the two exceptions to the newness rule for package names.
 The careful experimenter will note that if a package is created with a
 @('defpkg') that is subsequently undone, the host lisp system will contain the
 created package even after the undo.  Because ACL2 hangs onto @(see world)s
 after they have been undone, e.g., to implement @(':')@(tsee oops) but, more
 importantly, to implement error recovery, we cannot actually destroy a package
 upon undoing it.  Thus, the first exception to the newness rule is that
 @('name') is allowed to be the name of an existing package if that package was
 created by an undone @('defpkg') and the newly proposed set of imports is
 identical to the old one.  See @(see
 package-reincarnation-import-restrictions).  This exception does not violate
 the spirit of the newness rule, since one is disinclined to believe in the
 existence of undone packages.  The second exception is that @('name') is
 allowed to be the name of an existing package if the package was created by a
 @('defpkg') with identical set of imports.  That is, it is permissible to
 execute ``redundant'' @('defpkg') @(see command)s.  The redundancy test is
 based on the values of the two import forms (comparing them after sorting and
 removing duplicates), not on the forms themselves.</p>

 <p>Note that @('defpkg') performs evaluation in so-called @(see safe-mode),
 which can slow down evaluation significantly but checks @(see guard)s on
 @(see primitive)s.</p>

 <p>Finally, we explain why we require the package name not to contain
 lower-case characters.  We have seen at least one implementation that handled
 lower-case package names incorrectly.  Since we see no need for lower-case
 characters in package names, which can lead to confusion anyhow (note for
 example that @('foo::bar') is a symbol whose @(tsee symbol-package-name) is
 @('"FOO"'), not @('"foo"')), we simply disallow them.</p>

 <p>NOTE: Also see @(see managing-acl2-packages) for contributed documentation
 on managing ACL2 packages.</p>")

(defxdoc defproxy
  :parents (events)
  :short "Define a non-executable @(':')@(tsee program)-mode function for
  attachment"
  :long "<p>This event is provided for those who want to experiment with @(tsee
 defattach) using @(':')@(tsee program) mode functions, and without proof
 obligations or constraints on cycles in the extended ancestors graph; see
 @(see defattach).  If you merely want to define a stub or a non-executable
 function, see @(see defstub) or see @(see defun-nx), respectively.</p>

 <p>See community book @('books/misc/defproxy-test.lisp') for an extended (but
 simple) example.</p>

 @({
  Example Forms:
  (defproxy subr1 (* *) => *)
  (defproxy add-hash (* * hashtable) => (mv * hashtable))

  General Form:
  (defproxy name args-sig => output-sig)
 })

 <p>where @('name') is a new function symbol and @('(name . args-sig) =>
 output-sig)') is a signature; see @(see signature).</p>

 <p>The macro @('defproxy') provides a convenient way to introduce a ``proxy'':
 a @(':program') mode function that can be given attachments for execution (see
 @(see defattach)), assuming that there is an active trust tag (see @(see
 defttag)).  Thus, a @('defproxy') call expands to a @(tsee defun) form with
 the following @(tsee xargs) @(tsee declare) form: @(':non-executable
 :program').  Note that @(tsee verify-termination) is not permitted for such a
 function.  However, it is permitted to put the proxy function into
 @(':')@(tsee logic) mode by use of an @(tsee encapsulate) event; indeed, this
 is the way to ``upgrade'' an attachment so that the normal checks are
 performed and no trust tag is necessary.</p>

 <p>In order to take advantage of a @(tsee defproxy) form, one provides a
 subsequent @('defattach') form to attach an executable function to the
 @('defproxy')-introduced function.  When @(':skip-checks t') is provided in a
 @(tsee defattach) form, the usual checks for @('defattach') @(see events) are
 skipped, including proof obligations and the check that the extended ancestor
 relation has no cycles (see @(see defattach)).  There must be an active trust
 tag (see @(see defttag)) in order to use @(':skip-checks t').  In that case
 the use of @(':skip-checks t') is permitted; but note that its use is in fact
 required if a @(':')@(tsee program) mode function is involved, and even if a
 @(':')@(tsee logic) mode function is involved that has not been @(see
 guard)-verified.</p>

 <p>The following log shows a simple use of defproxy.</p>

 @({
  ACL2 !>(defproxy foo-stub (*) => *)

  Summary
  Form:  ( DEFUN FOO-STUB ...)
  Rules: NIL
  Time:  0.01 seconds (prove: 0.00, print: 0.00, other: 0.01)
   FOO-STUB
  ACL2 !>(foo-stub '(3 4 5))

  ACL2 Error in TOP-LEVEL:  ACL2 cannot ev the call of undefined function
  FOO-STUB on argument list:

  ((3 4 5))

  To debug see :DOC print-gv, see :DOC trace, and see :DOC wet.

  ACL2 !>(defun foo-impl (x)
           (declare (xargs :mode :program
                           :guard (or (consp x) (eq x nil))))
           (car x))

  Summary
  Form:  ( DEFUN FOO-IMPL ...)
  Rules: NIL
  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
   FOO-IMPL
  ACL2 !>(defttag t)

  TTAG NOTE: Adding ttag :T from the top level loop.
   T
  ACL2 !>(defattach (foo-stub foo-impl) :skip-checks t)

  Summary
  Form:  ( DEFATTACH (FOO-STUB FOO-IMPL) ...)
  Rules: NIL
  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
   :ATTACHMENTS-RECORDED
  ACL2 !>(foo-stub '(3 4 5))
  3
  ACL2 !>
 })

 <p>One can replace this attachment with one that uses @(':')@(tsee logic) mode
 functions and does not skip checks.  The idea is to reintroduce the proxy
 function using an @(tsee encapsulate) form, which does not require
 redefinition (see @(see ld-redefinition-action)) to be enabled, and either to
 put the attachment into @(':')@(tsee logic) mode with the @(see guard)
 verified, as we do in the example below, or else to attach to a different
 @(see guard)-verified @(':')@(tsee logic) mode function.</p>

 @({
  ACL2 !>(defattach (foo-stub nil) :skip-checks t) ; remove attachment

  Summary
  Form:  ( DEFATTACH (FOO-STUB NIL) ...)
  Rules: NIL
  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
   :ATTACHMENTS-RECORDED
  ACL2 !>(encapsulate
          ((foo-stub (x) t :guard (true-listp x)))
          (local (defun foo-stub (x) (cdr x)))
          (defthm foo-stub-reduces-acl2-count
            (implies (consp x)
                     (< (acl2-count (foo-stub x))
                        (acl2-count x)))))

  [[ ... output omitted here ... ]]

  The following constraint is associated with the function FOO-STUB:

  (IMPLIES (CONSP X) (< (ACL2-COUNT (FOO-STUB X)) (ACL2-COUNT X)))

  Summary
  Form:  ( ENCAPSULATE ((FOO-STUB ...) ...) ...)
  Rules: NIL
  Warnings:  Non-rec
  Time:  0.02 seconds (prove: 0.01, print: 0.00, other: 0.01)
   T
  ACL2 !>(verify-termination foo-impl)

  Since FOO-IMPL is non-recursive, its admission is trivial.  We could
  deduce no constraints on the type of FOO-IMPL.

  Computing the guard conjecture for FOO-IMPL....

  The guard conjecture for FOO-IMPL is trivial to prove.  FOO-IMPL is
  compliant with Common Lisp.

  Summary
  Form:  ( DEFUN FOO-IMPL ...)
  Rules: NIL
  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)

  Summary
  Form:  ( MAKE-EVENT (VERIFY-TERMINATION-FN ...))
  Rules: NIL
  Time:  0.01 seconds (prove: 0.00, print: 0.00, other: 0.01)
   FOO-IMPL
  ACL2 !>(defttag nil) ; optional
   NIL
  ACL2 !>(defattach (foo-stub foo-impl))

  The guard proof obligation is

  (IMPLIES (TRUE-LISTP X)
           (OR (CONSP X) (EQ X NIL))).

  But we reduce the conjecture to T, by primitive type reasoning.

  Q.E.D.

  This concludes the guard proof.

  We now prove that the attachment satisfies the required constraint.
  The goal to prove is

  (IMPLIES (CONSP X)
           (< (ACL2-COUNT (FOO-IMPL X))
              (ACL2-COUNT X))).

  [[ ... output omitted here ... ]]

  Q.E.D.

  Summary
  Form:  ( DEFATTACH (FOO-STUB FOO-IMPL))
  Rules: ((:DEFINITION ACL2-COUNT)
          (:DEFINITION FOO-IMPL)
          (:ELIM CAR-CDR-ELIM)
          (:FAKE-RUNE-FOR-LINEAR NIL)
          (:FAKE-RUNE-FOR-TYPE-SET NIL)
          (:REWRITE CAR-CONS)
          (:REWRITE CDR-CONS)
          (:TYPE-PRESCRIPTION ACL2-COUNT))
  Time:  0.02 seconds (prove: 0.01, print: 0.01, other: 0.00)
   :ATTACHMENTS-RECORDED
  ACL2 !>
 })

 <p>We close with some remarks on the checking of @(see guard)s in the case
 that @(tsee defattach) has been called with keyword argument @(':skip-checks
 t').  We illustrate with examples, where we assume an attachment pair @('(f
 . g)') created by an event @('(defattach ... (f g) ... :skip-checks t ...)').
 A good model for the treatment of @(':skip-checks t') is dependent on whether
 @('f') was introduced with @('defproxy') or with @(tsee encapsulate): for
 @('defproxy'), the normal guard-related checks are treated as skipped, while
 for @(tsee encapsulate), they are assumed to hold.</p>

 <p>First suppose that @('f') was introduced using @('defproxy'), and consider
 the following example.</p>

 @({
  (defproxy f (*) => *)
  (defun g (x) (car x)) ; not guard-verified; implicit guard of t is too weak
  (defttag t) ; trust tag needed for :skip-checks t
  (defattach (f g) :skip-checks t)
 })

 <p>If we try to evaluate the form @('(f 3)') in ACL2, then the
 executable-counterpart of @('f') is invoked (see @(see evaluation)).  It calls
 the executable-counterpart of @('g'), which calls the executable-counterpart
 of @(tsee car), which in turn checks the @(see guard) of @(tsee car) and
 causes a guard violation error (unless we first turn off guard-checking; see
 @(see set-guard-checking)).</p>

 @({
  ACL2 !>(trace$ f g)
   ((F) (G))
  ACL2 !>(f 3)
  1> (ACL2_*1*_ACL2::F 3)
    2> (ACL2_*1*_ACL2::G 3)

  ACL2 Error in TOP-LEVEL:  The guard for the function call (CAR X),
  which is (OR (CONSP X) (EQUAL X NIL)), is violated by the arguments
  in the call (CAR 3).  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 !>
 })

 <p>Little changes if we modify the example above by strengthening the guard of
 @('g').</p>

 @({
  (defproxy f (*) => *)
  (defun g (x)
    (declare (xargs :guard (consp x)))
    (car x))
  (defttag t) ; trust tag needed for :skip-checks t
  (defattach (f g) :skip-checks t)
 })

 <p>The result of evaluating @('(f 3)') is as before, except that this time the
 guard violation occurs at the time that @('g') is called.</p>

 @({
  ACL2 !>(trace$ f g)
   ((F) (G))
  ACL2 !>(f 3)
  1> (ACL2_*1*_ACL2::F 3)
    2> (ACL2_*1*_ACL2::G 3)

  ACL2 Error in TOP-LEVEL:  The guard for the function call (G X), which
  is (CONSP X), is violated by the arguments in the call (G 3).  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 !>
 })

 <p>Now consider a slight variation of the example just above, in which @('f')
 is introduced using @(tsee encapsulate) instead of using @('defproxy').</p>

 @({
  (encapsulate ( ((f *) => *) )
               (local (defun f (x) x)))
  (defun g (x)
    (declare (xargs :guard (consp x)))
    (car x))
  (defttag t) ; trust tag needed for :skip-checks t
  (defattach (f g) :skip-checks t)
 })

 <p>Since @('f') was introduced by @(tsee encapsulate) instead of by
 @('defproxy'), ACL2 assumes that the usual guard properties hold.  In
 particular, it assumes that (informally speaking) the guard of @('f') implies
 the guard of @('g'); see @(see defattach) for details.  So in this case, ACL2
 proceeds under that assumption even though it's actually false, and the result
 is a raw Lisp error.</p>

 @({
  ACL2 !>(trace$ f g)
   ((F) (G))
  ACL2 !>(f 3)
  1> (ACL2_*1*_ACL2::F 3)
    2> (G 3)

  ***********************************************
  ************ ABORTING from raw Lisp ***********
  ********** (see :DOC raw-lisp-error) **********
  Error:  Attempt to take the car of 3 which is not listp.
  ***********************************************

  If you didn't cause an explicit interrupt (Control-C),
  then it may help to see :DOC raw-lisp-error.

  To enable breaks into the debugger (also see :DOC acl2-customization):
  (SET-DEBUGGER-ENABLE T)
  ACL2 !>
 })

 <p>If you replace @('g') by its definition in the first example of this
 series, i.e. with a guard (implicitly) of @('t'), you will see the same error,
 this time because the @(tsee defattach) event assumed that @('g') was
 guard-verified.</p>")

(defxdoc defrec
  :parents (events)
  :short "Introduce a record structure, like a @('struct') in C."
  :long "<p>The @('defrec') macro is built into ACL2 and is frequently used in
 the ACL2 sources to define basic kinds of structures.</p>

 <h3>Better Alternatives to Defrec</h3>

 <p>While @('defrec') may be a reasonable choice for writing @(see
 program)-mode code, most users would likely be better served by using one of
 the many, richer alternatives to @(see defrec) that are available in various
 books.  See for instance macros such as:</p>

 <ul>
 <li>The @(see std::defaggregate) macro from @(see std/util),</li>
 <li>The @(see defdata) macro,</li>
 <li>The @(see fty::defprod) macro from the @(see fty::fty) library, and</li>
 <li>The @('data-structures/structures') book.</li>
 </ul>

 <p>A major reason to favor these macros over @('defrec') is that they
 introduce the constructors and accessors for the structure as proper
 functions, rather than mere macros.  This is very helpful when you are trying
 to use ACL2 to reason about code that works with structures.  For instance, it
 means that your proof goals will involve terms like @('(employee->position
 x)') instead of @('(cdddr x)').</p>

 <p>Another reason is that @('defrec') does not support putting constraints on
 the fields of your structure.  For instance, you might want to have an
 @('employee') structure where the @('name') field is always a string.  You
 can't do this with @('defrec'), but any of the above macros support it.</p>

 <p>Some of the above macros also have other useful features, e.g., integration
 with @(see b*), support for @(see xdoc) documentation, and so forth.</p>

 <h3>Usage</h3>

 <p>A typical use of @('defrec') might look like this:</p>

 @({
     (defrec employee             ;; name of the structure
       (name salary . position)   ;; fields of the structure
       nil)                       ;; "cheap" flag
 })

 <p>This will result in the introduction of:</p>

 <ul>

 <li>A "weak" recognizer function, @('weak-employee-p'), which recognizes
 cons structures that have the right shape.  We call the recognizer <i>weak</i>
 because it doesn't impose any constraints on the fields, e.g., there is no
 requirement that the @('name') of an employee must be a string or that the
 @('salary') must be a number.</li>

 <li>A @(see make) macro that can be used like this:
     @({
        (make employee :name "Jimmy"
                       :salary 0
                       :position "Unpaid Intern")
     })</li>

 <li>A @(see change) macro that can be used like this:
     @({
         (let ((jimmy (make-employee :name "Jimmy" ...)))
           (change employee jimmy :salary 300000
                                  :position "Vice President"))
     })</li>

 <li>Suitable @(see access) macros that can be used like this:
     @({
         (let ((jimmy (make-employee :name "Jimmy" ...)))
           (access employee jimmy :name))
     })</li>

 </ul>")

(defxdoc defrefinement
  :parents (events)
  :short "Prove that @('equiv1') refines @('equiv2')"
  :long "@({
  Example:
  (defrefinement equiv1 equiv2)

  is an abbreviation for
  (defthm equiv1-refines-equiv2
    (implies (equiv1 x y) (equiv2 x y))
    :rule-classes (:refinement))
 })

 <p>See @(see refinement).</p>

 @({
  General Form:
  (defrefinement equiv1 equiv2
    :package package
    :event-name event-name
    :rule-classes rule-classes
    :instructions instructions
    :hints hints
    :otf-flg otf-flg)
 })

 <p>where @('equiv1') and @('equiv2') are known @(see equivalence) relations;
 @('package'), if supplied, is one of @(':current'), @(':equiv1'), @(':equiv2')
 or @(':legacy'); @('event-name'), if supplied, is a symbol; and all other
 arguments are as specified in the documentation for @(tsee defthm).  The
 @('defrefinement') macro expands into a call of @(tsee defthm).  The name of
 the @(tsee defthm) event is @('equiv1-refines-equiv2'), unless an
 @(':event-name') keyword argument is supplied, in which case @('event-name')
 is used as the name.  The @('package') of symbols generated, such as variables
 and @(tsee defthm) names, is determined by the @('package') argument: if it is
 not supplied or its value is @(':current'), then the @(tsee current-package)
 is used; if its value is @(':equiv1') or @(':legacy'), then the package of
 @(':equiv1') is used; if its value is @(':equiv2'), then the package of
 @(':equiv2') is used.  The rule-class @(':')@(tsee refinement) is added to the
 @(tsee rule-classes) specified, if it is not already there.  All other
 arguments to the generated @(tsee defthm) form are as specified by the other
 keyword arguments above.  The term generated for the @(tsee defthm) event
 states that @('equiv1') refines @('equiv2'). </p>")

(defxdoc defstobj
  :parents (events stobj)
  :short "Define a new single-threaded object"
  :long "<p>Note: Novices are advised to avoid @('defstobj'), perhaps instead
 using community books @(see std::defaggregate) or
 @('books/data-structures/structures.lisp').  At the least, consider using
 @('(')@(tsee set-verify-guards-eagerness)@(' 0)') to avoid @(see guard)
 verification.  On the other hand, after you learn to use @('defstobj'), see
 @(see defabsstobj) for another way to introduce single-threaded objects.</p>

 @({
  Example:
  (defconst *mem-size* 10) ; for use of *mem-size* just below
  (defstobj st
            (reg :type (array (unsigned-byte 31) (8))
                 :initially 0)
            (p-c :type (unsigned-byte 31)
                 :initially 555)
            halt   ; = (halt :type t :initially nil)
            (mem :type (array (unsigned-byte 31) (*mem-size*))
                 :initially 0 :resizable t)
            (ht  :type (hash-table eq 70 integer) :initially 0))

  General Form:
  (defstobj name
            (field1 :type type1
                    :element-type etype1
                    :initially val1
                    :resizable b1)
            ...
            (fieldk :type typek
                    :element-type etypek
                    :initially valk
                    :resizable bk)
            :renaming doublets
            :inline flg
            :congruent-to old-stobj-name
            :non-memoizable nm-flg
            :non-executable ne-flg)
 })

 <p>where @('name') is a new symbol; each @('fieldi') is a symbol; each
 @('typei') is either a type-indicator (a @(tsee type-spec) or @(see stobj)
 name), of the form @('(ARRAY type-indicator (max))'), or of one of the forms
 @('(HASH-TABLE test)'), @('(HASH-TABLE test size)'), @('(HASH-TABLE test size
 type-indicator)'), @('(STOBJ-TABLE)'), or @('(STOBJ-TABLE size)'); each
 @('vali') is an object satisfying @('typei'); and each @('bi') is @('t') or
 @('nil').  Pairs @(':element-type etypei'), @(':initially vali'), and
 @(':resizable bi') may be omitted; more on this below.  The @(':renaming
 doublets') argument is optional and allows the user to override the default
 function names introduced by this event.  The @(':inline flg') Boolean
 argument is also optional and declares to ACL2 that the generated access and
 update functions for the stobj should be implemented as macros under the
 hood (which has the effect of inlining the function calls).  The optional
 @(':congruent-to old-stobj-name') argument specifies an existing stobj with
 exactly the same structure, and is discussed below.  The optional
 @(':non-memoizable nm-flg') and @(':non-executable ne-flg') Boolean arguments
 are ignored when @('nm-flg') and @('ne-flg') are @('nil'), but otherwise: the
 former instructs ACL2 to lay down faster code for functions that return the
 new stobj but disallows @(see memoization) of any function that takes the new
 stobj as an argument; and the latter avoids actually creating a global
 stobj (details follow later below).  We describe further restrictions on the
 @('fieldi'), @('typei'), @('vali'), and on @('doublets') below.  We recommend
 that you read about single-threaded objects (stobjs) in ACL2 before
 proceeding; see @(see stobj).</p>

 <p>The effect of this event is to introduce a new single-threaded object
 (i.e., a ``@(see stobj)''), named @('name'), and the associated recognizers,
 creator, accessors, updaters, constants.  For fields of @('ARRAY') type, this
 event also introduces length and resize functions.  For fields of
 @('HASH-TABLE') type, this event also introduces boundp, get?, remove, count,
 clear, and initialization functions.  Fields of @('STOBJ-TABLE') type
 introduce those functions as well except for the get? function.</p>

 <h3>The Single-Threaded Object Introduced</h3>

 <p>The @('defstobj') event effectively introduces a new ``live stobj'' object,
 named @('name'), which has as its initial logical value a list of @('k')
 elements, where @('k') is the number of ``field descriptors'' provided.  This
 object has mutable updates: that is, the object is actually modified in place,
 rather than copied, where for an array or hash-table field the update is made
 to a corresponding raw Lisp array or hash table (respectively).  This is only
 possible because of syntactic restrictions enforced by ACL2 when programming
 with stobjs, so that after modifying a stobj, its old versions are no longer
 accessible.</p>

 <p>The elements are listed in the same order in which the field descriptors
 appear.  If the @(':type') of a field is @('(ARRAY type-indicator (max))')
 then @('max') is a non-negative integer or a symbol introduced by @(tsee
 defconst)) whose value is a non-negative integer, and the corresponding
 element of the stobj is initially of length specified by @('max').  If the
 @(':type') of a field is @('(HASH-TABLE test)') or @('(HASH-TABLE test
 size)'), or @('(HASH-TABLE test size type-indicator)'), then: @('test') is one
 of the symbols @('EQ'), @('EQL'), @('HONS-EQUAL'), or @('EQUAL'); @('size'),
 if supplied as above or in @('(STOBJ-TABLE size)'), is nil (handled the same
 as when size is omitted) or a natural number; and @('type-indicator') restrict
 the values that can be stored, as discussed in the next paragraph.  The
 hash-table test is applied when looking up keys in the associated raw Lisp
 hash table, where @(tsee hons-copy) is first applied to the key in the
 @('HONS-EQUAL') case; and the size is a hint to the host Lisp for the initial
 size of the associated hash table in raw Lisp.  (The size really is used only
 as a hint.  Indeed, at least one host Lisp does not support size 0, so ACL2
 simply treats size 0 as size 1; and even size 1 may result in a hash table of
 considerably larger size.)</p>

 <p>If the value of @(':type') is of the form @('(ARRAY type-indicator
 (max))'), @('(HASH-TABLE test size type-indicator)'), or just
 @('type-indicator'), then @('type-indicator') is typically a type-spec; see
 @(see type-spec).  However, @('type-indicator') can also be the name of a
 stobj that was previously introduced (by @('defstobj') or @(tsee
 defabsstobj)).  We ignore this ``nested stobj'' case below; see @(see
 nested-stobjs) for a discussion of stobjs within stobjs.</p>

 <p>A field with a @('STOBJ-TABLE') type is logically an association list whose
 keys are @(see stobj) names.  ACL2 maintains the execution invariant that each
 key is mapped to a stobj satisfying that key's recognizer.  We say little more
 here about stobj-tables; see @(see stobj-table) for relevant discussion.</p>

 <p>Below, we refer to <i>scalar types</i> as stobj field types that are
 neither array types, hash-table types, nor stobj-table types.  Now consider
 the keyword value @(':initially val') for a stobj field.  If the stobj field
 is of scalar type, then @('val') is the initial value of the field.  For an
 array type @('(ARRAY type-indicator (max))'), @('val') is the initial value of
 the elements in the corresponding array.  For a @('HASH-TABLE') type, @('val')
 is the value obtained when looking up a key that is not bound in the
 hash table; think of it as the default value for lookups.  Finally, the
 @(':initially') keyword is illegal for fields of @('STOBJ-TABLE') type.</p>

 <p>Note that the actual representation of the stobj in the underlying Lisp may
 be quite different; see @(see stobj-example-2).  For the moment we focus
 primarily on the logical aspects of the object.</p>

 <p>In addition, the @('defstobj') event introduces functions for recognizing
 and creating the stobj and for recognizing, accessing, and updating its
 fields.  For fields of @('ARRAY') type, length and resize functions are also
 introduced; see @(see defstobj-element-type) for discussion of the
 @(':element-type') keyword that may be provided for performance .  For fields
 of @('HASH-TABLE') or @('STOBJ-TABLE') type, this event also introduces
 boundp, get? (@('HASH-TABLE') types only), remove, count, clear, and
 initialization functions, as discussed below.  Constants are introduced that
 correspond to the accessor functions.</p>

 <h3>Restrictions on the Field Descriptions in Defstobj</h3>

 <p>Each field descriptor is of the form:</p>

 @({
  (fieldi :TYPE typei :INITIALLY vali)
 })

 <p>Note that the type and initial value are given in ``keyword argument''
 format and may be given in either order.  The @('typei') and @('vali')
 ``arguments'' are not evaluated.  If omitted, the type defaults to @('t')
 (unrestricted) and the initial value defaults to @('nil').</p>

 <p>Each @('typei') must be either a @(tsee type-spec) or else a list of the
 form @('(ARRAY type-spec (max))'), @('(HASH-TABLE test)'), @('(HASH-TABLE test
 size)'), @('(HASH-TABLE test size type-spec)'), @('(STOBJ-TABLE)'), or
 @('(STOBJ-TABLE size)').  (Again, we are ignoring the case of nested stobjs,
 discussed elsewhere (see @(see nested-stobjs)), where a type-spec may be
 replaced by a stobj name.)  The latter forms are said to be ``array types'',
 ``hash-table types'', and stobj-table types (again, not discussed much here;
 see @(see stobj-table)).  Examples of legal @('typei') are:</p>

 @({
  (INTEGER 0 31)
  (SIGNED-BYTE 31)
  (ARRAY (SIGNED-BYTE 31) (16))
  (ARRAY (SIGNED-BYTE 31) (*c*)) ; where *c* has a non-negative integer value
  (HASH-TABLE HONS-EQUAL 70)
  (HASH-TABLE EQL NIL (INTEGER 0 *))
  (STOBJ-TABLE 70)
 })

 <p>The @('typei') describes the objects which are expected to occupy the given
 field.  Those objects in @('fieldi') should satisfy @('typei').  We are more
 precise below about what we mean by ``expected.''  Below we present the
 restrictions on @('typei') and @('vali').</p>

 <p>Remark on @('SATISFIES').  As suggested above, each type indicator must be
 a legal @(see type-spec) or a stobj name.  But if it is a type-spec involving
 @('(SATISFIES pred)'), then not only must @('pred') be a unary @(':')@(tsee
 logic) mode function symbol, but the type-spec is subject to a form of @(see
 guard) verification.  For example, the type-spec @('(SATISFIES evenp)') is not
 legal for a stobj field because the guard generated for @('(evenp x)') is
 @('(integerp x)').  However, the following is legal.</p>

 @({
 (defun my-evenp (x)
   (declare (xargs :guard t))
   (and (integerp x) (evenp x)))
 (defstobj st (fld :type (satisfies my-evenp) :initially 4))
 })

 <p>The following is also legal, as explained below.</p>

 @({
 (defstobj st (a :type (and integer (satisfies evenp)) :initially 0))
 })

 <p>The type-spec displayed immediately above is legal because it generates the
 term @('(and (integerp x) (evenp x)')), which macroexpands to @('(if (integerp
 x) (evenp x) nil)') and hence can be trivially guard-verified.</p>

 <p>To understand this notion of trivial guard verification, first note that
 every type-spec gives rise to a corresponding term in the variable @('x'), as
 in the example just above.  If the type-spec uses @('SATISFIES'), then the
 guard proof obligation for that term is subject to the limited simplification
 used by @(tsee verify-guards) with option @(':guard-simplify :limited'); see
 @(see verify-guards), specifically regarding that option.  The requirement is
 that this limited simplifcation completes the proof, without further
 simplification or a call to the theorem prover.  This restriction to limited
 simplification is probably not much of a restriction for typical uses of
 @('SATISFIES') in type-specs.  End of Remark on @('SATISFIES').</p>

 <h3>Scalar Types</h3>

 <p>We first discuss types that are neither array types, hash-table types, nor
 stobj-table types.  We call these ``scalar types.''</p>

 <p>When @('typei') is a @(tsee type-spec) it restricts the contents, @('x'),
 of @('fieldi') according to the ``meaning'' formula given in the table for
 @(tsee type-spec).  For example, the first @('typei') above restricts the
 field to be an integer between 0 and 31, inclusive.  The second restricts the
 field to be an integer between -2^30 and (2^30)-1, inclusive.</p>

 <p>The initial value, @('vali'), of a field description may be any ACL2 object
 but must satisfy @('typei').  Note that @('vali') is not a form to be
 evaluated but an object.  A form that evaluates to @('vali') could be written
 @(''vali'), but @('defstobj') does not expect you to write the quote mark.
 For example, the field description</p>

 @({
  (days-off :initially (saturday sunday))
 })

 <p>describes a field named @('days-off') whose initial value is the list
 consisting of the two symbols @('SATURDAY') and @('SUNDAY').  In particular,
 the initial value is NOT obtained by applying the function @('saturday') to
 the variable @('sunday')!  Had we written</p>

 @({
  (days-off :initially '(saturday sunday))
 })

 <p>it would be equivalent to writing</p>

 @({
  (days-off :initially (quote (saturday sunday)))
 })

 <p>which would initialize the field to a list of length two, whose first
 element is the symbol @('quote') and whose second element is a list containing
 the symbols @('saturday') and @('sunday').</p>

 <h3>Array Types</h3>

 <p>When @('typei') is of the form @('(ARRAY type-spec (max))'), the field is
 supposed to be a list of items, initially of length specified by @('max'),
 each of which satisfies the indicated @('type-spec').  @('Max') must be a
 non-negative integer or a defined constant evaluating to a non-negative
 integer.  Thus, each of</p>

 @({
  (ARRAY (SIGNED-BYTE 31) (16))
  (ARRAY (SIGNED-BYTE 31) (*c*)) ; given previous event (defconst *c* 16)
 })

 <p>restricts the field to be a list of integers, initially of length 16, where
 each integer in the list is a @('(SIGNED-BYTE 31)').  We sometimes call such a
 list an ``array'' (because it is represented as an array in the underlying
 Common Lisp).  The elements of an array field are indexed by position,
 starting at 0.  Thus, the maximum legal index of an array field one less than
 is specified by @('max').  Note that the value of @('max') must be less than
 the Common Lisp constant @('array-dimension-limit'), and also (though this
 presumably follows) less than the Common Lisp constant
 @('array-total-size-limit').</p>

 <p>Note also that the @('ARRAY') type requires that the @('max') be enclosed
 in parentheses.  This makes ACL2's notation consistent with the Common Lisp
 convention of describing the (multi-)dimensionality of arrays.  But ACL2
 currently supports only single dimensional arrays in stobjs.</p>

 <p>For array fields, the initial value @('vali') must be an object satisfying
 the @(tsee type-spec) of the @('ARRAY') description.  The initial value of the
 field is a list of @('max') repetitions of @('vali').</p>

 <p>Array fields can be ``resized,'' that is, their lengths can be changed, if
 @(':resizable t') is supplied as shown in the example and General Form above.
 The new length must satisfy the same restriction as does @('max'), as
 described above.  Each array field in a @('defstobj') event gives rise to a
 length function, which gives the length of the field, and a resize function,
 which modifies the length of the field if @(':resizable t') was supplied with
 the field when the @('defstobj') was introduced and otherwise causes an error.
 If @(':resizable t') was supplied and the resize function specifies a new
 length @('k'), then: if @('k') is less than the existing array length, the
 array is shortened simply by dropping elements with index at least @('k');
 otherwise, the array is extended to length @('k') by mapping the new indices
 to the initial value (supplied by @(':initially'), else default @('nil')).</p>

 <p>Array resizing is relatively slow, so we recommend using it somewhat
 sparingly.</p>

 <p>See @(see defstobj-element-type) for how the @(':element-type') field may
 help with performance.</p>

 <h3>Hash-table Types</h3>

 <p>When @('typei') is of the form @('(HASH-TABLE test size type-spec)'), where
 @('size') and @('type-spec') are optional, the field is logically an
 association list, initially empty, accessed using function @(tsee
 hons-assoc-equal) (which is convenient simply because it has a guard of
 @('t'), as opposed to other flavors of @(tsee assoc)).  Under the hood in raw
 Lisp, however, there is a corresponding hash table that represents the same
 association of keys with values as does the association list.  Each key should
 be comparable with arbitrary objects using the specified @('test'): thus if
 @('test') is @(tsee EQUAL) then there is no restriction on keys; if @('test')
 is @(tsee EQ) or @(tsee EQL) then the keys must be symbols or satisfy @(tsee
 eqlablep), respectively; and if @('test') is @(tsee HONS-EQUAL) then there is
 no restriction on keys, but each proposed key is @(tsee hons)ed in raw Lisp
 before it is used (whether for access or update) and before it is put into the
 underlying hash table.  The @('size') defaults to @('nil'), and if supplied,
 it must be either @('nil') or a non-negative integer, or else a defined
 constant evaluating to @('nil') or a non-negative integer.  When the value is
 a (non-negative) integer, it may be used by the host Lisp as a hint for how to
 size the associated hash table in raw Lisp.</p>

 <p>For a hash-table field, the @(':initially') keyword specifies a default
 rather than an initial value: it provides the value (default @('nil'))
 returned by an accessor when a given key is not bound.</p>

 <p>A hash-table field is associated not only with a recognizer, an accessor,
 and an updater, but also with the following functions, whose final argument is
 the stobj name but that may also take a key or, in the case of the ``init''
 function, three other arguments, as follows:</p>

 <ul>

 <li>a ``boundp'' function to check whether a given key is bound;</li>

 <li>a ``get?'' function that, for a given key, returns two values @('(mv val
 boundp)'), where: if the given key is bound then @('val') is its value and
 @('boundp') is @('t'), else @('val') is as specified by the @(':initially')
 keyword (@('nil') by default) and @('boundp') is @('nil');</li>

 <li>a ``remove'' function for removing a given key;</li>

 <li>a ``count'' function that returns the number of (distinct) bound
 keys;</li>

 <li>a ``clear'' function that creates a new empty hash table (and logically,
 the empty alist);</li>

 <li>an ``init'' function that takes a given size, rehash-size, and
 rehash-threshold (and the stobj name) and creates a new empty hash table (and
 logically, the empty alist) by passing these parameters to the raw Lisp
 function, @('(make-hash-table)'), that creates a hash table.</li>

 </ul>

 <p>The clear and init functions both use the @('size') argument, if supplied
 and not @('nil'), of the type of the field supplied in the @('defstobj')
 event.  If a non-@('nil') @('size') argument was not supplied in that type,
 then the size of the hash table depends on the host Lisp.</p>

 <h3>Stobj-table Types</h3>

 <p>As noted above, these are not discussed much here; see @(see
 stobj-table).</p>

 <h3>The Default Function Names</h3>

 <p>To recap, in</p>

 @({
  (defstobj name
            (field1 :type type1 :initially val1)
            ...
            (fieldk :type typek :initially valk)
            :renaming doublets
            :inline inline-flag)
 })

 <p>@('name') must be a new symbol, each @('fieldi') must be a symbol, each
 @('typei') must be a @(tsee type-spec) or @('(ARRAY type-spec (max))'), and
 each @('vali') must be an object satisfying @('typei').</p>

 <p>Roughly speaking, for each @('fieldi'), a @('defstobj') introduces a
 recognizer function, an accessor function, and an updater function.  The
 accessor function, for example, takes the stobj and returns the indicated
 component; the updater takes a new component value and the stobj and return a
 new stobj with the component replaced by the new value.  But that summary is
 inaccurate for array, hash-table, and stobj-table fields.</p>

 <p>The accessor function for an array field does not take the stobj and return
 the indicated component array, which is a list of length specified by
 @('max').  Instead, it takes an additional index argument and returns the
 indicated element of the array component.  Similarly, the updater function for
 an array field takes an index, a new value, and the stobj, and returns a new
 stobj with the indicated element replaced by the new value.</p>

 <p>The accessor and updater functions for a hash-table field are analogous to
 those for array fields.  Thus, the accessor takes an additional key argument
 and returns the associated value, or nil if the key is not bound.  The updater
 function takes a key, a new value, and the stobj, and returns a new stobj with
 the indicated element replaced by the new value.  See @(see stobj-table) for a
 discussion of stobj-table types, which are largely ignored below.</p>

 <p>These functions &mdash; the recognizer, accessor, and updater, and also
 length and resize functions in the case of array fields, and boundp, get?,
 remove, count, clear, and init functions in the case of hash-table fields
 &mdash; have ``default names.''  The default names depend on the field name,
 @('fieldi'), and on whether the field is an array field, a hash-table field,
 or neither (i.e., a scalar field).  For clarity, suppose @('fieldi') is named
 @('c'). The default names are shown below in calls, which also indicate the
 arities of the functions.  In the expressions, we use @('x') as the object to
 be recognized by field recognizers, @('i') as an array index or the size of a
 resized array, @('k') as a key (for the logical association list or raw-Lisp
 hash table associated with the field), @('v') as the ``new value'' to be
 installed by an updater, and @('name') as the single-threaded object.</p>

 @({
              scalar field        array field          hash-table field
                                                       and stobj-table field
  recognizer  (cP x)              (cP x)               (cP x)
  accessor    (c name)            (cI i name)
                                      hash-table access: (c-get k name)
                                     stobj-table access: (c-get k name default)
  updater     (UPDATE-c v name)   (UPDATE-cI i v name) (c-put k v name)
  length                          (c-LENGTH name)
  resize                          (RESIZE-c i name)
  boundp                                               (c-boundp k name)
  get? [For hash-tables only, not stobj-tables]        (c-get? k name)
  remove                                               (c-rem k name)
  count                                                (c-count name)
  clear                                                (c-clear name)
  init                                                 (c-init ht-size
                                                               rehash-size
                                                               rehash-threshold
                                                               name)
 })

 <p>Finally, a recognizer and a creator for the entire single-threaded object
 are introduced.  The creator returns the initial stobj, but may only be used
 in limited contexts; see @(see with-local-stobj).  If the single-threaded
 object is named @('name'), then the default names and arities are as shown
 below.</p>

 @({
  top recognizer     (nameP x)
  creator            (CREATE-name)
 })

 <p>For example, the event</p>

 @({
  (DEFSTOBJ $S
    (X :TYPE INTEGER :INITIALLY 0)
    (A :TYPE (ARRAY (INTEGER 0 9) (3)) :INITIALLY 9)
    (H :TYPE (HASH-TABLE EQ)))
 })

 <p>introduces a stobj named @('$S').  The stobj has three fields: @('X'),
 @('A'), and @('H').  The @('A') field is an array and the @('A') field is
 a hash table.  The @('X') field contains an integer and is initially 0.  The
 @('A') field contains a list of integers, each between 0 and 9, inclusive.
 Initially, each of the three elements of the @('A') field is 9.</p>

 <p>This event introduces the following sequence of definitions:</p>

 @({
  (DEFUN XP (X) ...)               ; recognizer for X field
  (DEFUN AP (X) ...)               ; recognizer of A field
  (DEFUN HP (X) ...)               ; recognizer of H field
  (DEFUN $SP ($S) ...)             ; top-level recognizer for stobj $S
  (DEFUN CREATE-$S () ...)         ; creator for stobj $S
  (DEFUN X ($S) ...)               ; accessor for X field
  (DEFUN UPDATE-X (V $S) ...)      ; updater for X field
  (DEFUN A-LENGTH ($S) ...)        ; length of A field
  (DEFUN RESIZE-A (I $S) ...)      ; resizer for A field
  (DEFUN AI (I $S) ...)            ; accessor for A field at index I
  (DEFUN UPDATE-AI (I V $S) ...)   ; updater for A field at index I
  (DEFUN H-GET (K $S) ...)         ; accessor for H field at key K
  (DEFUN H-PUT (K V $S) ...)       ; updater for H field at key K
  (DEFUN H-BOUNDP (K $S) ...)      ; t if key k is bound in H, else nil
  (DEFUN H-GET? (K $S) ...)        ; (mv val t) if key is bound in H to val;
                                   ;   (mv nil nil) if key is not bound in H
  (DEFUN H-REM (K $S) ...)         ; remove key K from field H
  (DEFUN H-COUNT ($S) ...)         ; the number of (distinct) keys in field H
  (DEFUN H-CLEAR ($S) ...)         ; empty the hash table for field H
  (DEFUN H-INIT (HT-SIZE REHASH-SIZE REHASH-THRESHOLD $S) ...)
                                   ; replace the hash table for field H with
                                   ;   with a new, empty hash table with the
                                   ;   given hints as described below
 })

 <p>For the last of these, the values of @('HT-SIZE'), @('REHASH-SIZE'), and
 @('REHASH-THRESHOLD') are passed to the @(':size'), @(':rehash-size'), and
 @(':reash-threshold') arguments (respectively) of a call of
 @('make-hash-table') in raw Lisp.  The @(':test') argument of this function is
 the one specified in the @(':type') specified in the @('defstobj') event for
 the field, in this case @('EQ') from the type @('(HASH-TABLE EQ)'); note
 however that if the @(':type') specifies the test @('HONS-EQUAL'), then the
 @(':test') is @('EQL').</p>

 <h3>Avoiding the Default Function Names</h3>

 <p>If you do not like the default names listed above you may use the optional
 @(':renaming') doublets to substitute names of your own choosing.  Each
 element of @('doublets') should be of the form @('(fn1 fn2)'), where @('fn1')
 is a default name and @('fn2') is your choice for that name.</p>

 <p>For example</p>

 @({
  (DEFSTOBJ $S
    (X :TYPE INTEGER :INITIALLY 0)
    (A :TYPE (ARRAY (INTEGER 0 9) (3)) :INITIALLY 9)
    :renaming ((X XACCESSOR) (CREATE-$S MAKE$S)))
 })

 <p>introduces the following definitions</p>

 @({
  (DEFUN XP (X) ...)               ; recognizer for X field
  (DEFUN AP (X) ...)               ; recognizer of A field
  (DEFUN $SP ($S) ...)             ; top-level recognizer for stobj $S
  (DEFUN MAKE$S () ...)            ; creator for stobj $S
  (DEFUN XACCESSOR ($S) ...)       ; accessor for X field
  (DEFUN UPDATE-X (V $S) ...)      ; updater for X field
  (DEFUN A-LENGTH ($S) ...)        ; length of A field
  (DEFUN RESIZE-A (K $S) ...)      ; resizer for A field
  (DEFUN AI (I $S) ...)            ; accessor for A field at index I
  (DEFUN UPDATE-AI (I V $S) ...)   ; updater for A field at index I
 })

 <p>Note that even though the renaming doublets substitutes ``@('XACCESSOR')''
 for ``@('X')'' the updater for the @('X') field is still called
 ``@('UPDATE-X').''  That is because the renaming is applied to the default
 function names, not to the field descriptors in the event.</p>

 <p>Use of the @(':renaming') doublets may be necessary to avoid name clashes
 between the default names and pre-existing function symbols.</p>

 <h3>Constants</h3>

 <p>@('Defstobj') events also introduce constant definitions (see @(see
 defconst)).  One constant is introduced for each accessor function by
 prefixing and suffixing a `@('*')' character on the function name.  The value
 of that constant is the position of the field being accessed.  For example, if
 the accessor functions are @('a'), @('b'), and @('c'), in that order, then the
 following constant definitions are introduced.</p>

 @({
  (defconst *a* 0)
  (defconst *b* 1)
  (defconst *c* 2)
 })

 <p>These constants are used for certain calls of @(tsee nth) and @(tsee
 update-nth) that are displayed to the user in proof output.  For example, for
 stobj @('st') with accessor functions @('a'), @('b'), and @('c'), in that
 order, the term @('(nth '2 st)') would be printed during a proof as @('(nth
 *c* st)').  Also see @(see term), in particular the discussion there of
 untranslated terms, and see @(see nth-aliases-table).</p>

 <h3>The Effects of a <tt>Defstobj</tt></h3>

 <p>Because the stobj functions are introduced as ``sub-events'' of the
 @('defstobj') the history commands @(':')@(tsee pe) and @(':')@(tsee pc) will
 not print the definitions of these functions but will print the superior
 @('defstobj') event.  To see the definitions of these functions use the
 history command @(':')@(tsee pcb!).</p>

 <p>To see an s-expression containing the definitions that constitute the raw
 Lisp implementation of the event, evaluate the form</p>

 @({
  (nth 4 (global-val 'cltl-command (w state)))
 })

 <p><i>immediately after</i> the @('defstobj') event has been processed.  Those
 functions that contain @('(DECLARE (STOBJ-INLINE-FN T))') will generate @(tsee
 defabbrev) forms because the @(':inline') keyword of @('defstobj') was
 supplied the value @('t').  The rest will generate @(tsee defun) forms.</p>

 <p>Evaluation of a @('defstobj') event @(see disable)s the @(see
 executable-counterpart) of the creator function.  This is useful for proofs,
 since calls of that function always cause an error (albeit one which is
 handled during proofs).</p>

 <p>A @('defstobj') is considered redundant only if it is syntactically
 identical to a previously executed @('defstobj').  Note that a redundant
 @('defstobj') does not reset the @(see stobj) fields to their initial
 values.</p>

 <h3>Performance</h3>

 <p>The @(':inline') keyword argument controls whether or not the functions
 introduced are inlined (as macros under the hood, in raw Lisp), with the
 exception of the resize function.  If @(':inline t') is provided then these
 are inlined; otherwise they are not.  The advantage of inlining is potentially
 better performance; there have been contrived examples, doing essentially
 nothing except accessing and updating array fields, where inlining reduced the
 time by a factor of 10 or more; and inlining has sped up realistic examples by
 a factor of at least 2.  Inlining may get within a factor of 2 of C execution
 times for such contrived examples, and perhaps within a few percent of C
 execution times on realistic examples.</p>

 <p>A drawback to inlining is that redefinition may not work as expected, much
 as redefinition may not work as expected for macros: defined functions that
 call a macro, or an inlined stobj function, will not see a subsequent
 redefinition of the macro or inlined function.  Another drawback to inlining
 is that because inlined functions are implemented as macros in raw Lisp,
 tracing (see @(see trace$)) will not show their calls.  These drawbacks are
 avoided by default, but the user who is not concerned about them is advised to
 specify @(':inline t').</p>

 <p>It can also improve performance to specify @(':non-memoizable t'), which
 disallows memoization but therefore avoids the cost of certain ``flushing''
 operations.</p>

 <p>See @(see defstobj-element-type) for performance considerations pertaining
 to the @(':element-type') field.</p>

 <h3>Specifying Congruent Stobjs</h3>

 <p>Two stobjs are may be considered to be ``congruent'' if they have the same
 structure, that is, their @('defstobj') events are identical when ignoring
 field names.  In particular, every stobj is congruent to itself.  In order to
 tell ACL2 that a new stobj @('st2') is indeed to be considered as congruent to
 an existing stobj @('st1'), the @('defstobj') event introducing @('st2') is
 given the keyword argument @(':congruent-to st1').  Congruence is an
 equivalence relation: when you specify a new stobj to be congruent to an old
 one, you are also specifying that the new stobj is congruent to all other
 stobjs that are congruent to the old one.  Thus, continuing the example above,
 if you specify that @('st3') is @(':congruent-to st2'), then @('st1'),
 @('st2'), and @('st3') will all be congruent to each other.</p>

 <p>When two stobjs are congruent, ACL2 allows you to substitute one for
 another in a function call.  Any number of stobjs may be replaced with
 congruent stobjs in the call, provided no two get replaced with the same
 stobj.  The return values are correspondingly modified: if stobj @('st1') is
 replaced by @('st2') at an argument position, and if @('st1') is returned in
 the output @(see signature) of the function, then @('st2') is returned in
 place of @('st1').</p>

 <p>The following example illustrates congruent stobjs.  For more examples of
 how to take advantage of congruent stobjs, and also of how to misuse them, see
 community book @('books/misc/congruent-stobjs-test.lisp').</p>

 @({
  (defstobj st1 fld1)
  (defstobj st2 fld2 :congruent-to st1)
  (defstobj st3 fld3 :congruent-to st2) ; equivalently, :congruent-to st1
  (defun f (st1 st2 st3)
    (declare (xargs :stobjs (st1 st2 st3)))
    (list (fld2 st1) (fld3 st2) (fld1 st3)))
  (update-fld1 1 st1)
  (update-fld1 2 st2) ; notice use of update-fld1 on st2
  (update-fld1 3 st3) ; notice use of update-fld1 on st3
  (assert-event (equal (f st3 st2 st1) '(3 2 1)))
 })

 <p>The following example shows an error that occurs when stobj arguments are
 repeated, i.e., at least two stobj arguments (in this case, three) get
 replaced by the same stobj.</p>

 @({
  ACL2 !>(f st1 st1 st1)

  ACL2 Error in TOP-LEVEL:  The form ST1 is being used, as an argument
  to a call of F, where the single-threaded object ST2 was expected,
  even though these are congruent stobjs.  See :DOC defstobj, in particular
  the discussion of congruent stobjs.  Note:  this error occurred in
  the context (F ST1 ST1 ST1).

  ACL2 !>
 })

 <h3>Specifying Non-executable Stobjs</h3>

 <p>As noted above, if keyword argument @(':non-executable t') is specified
 then no global stobj for the given name is created.  See @(see
 add-global-stobj) for a discussion of global stobjs, but in a nutshell, a
 global stobj is a ``live'', mutable stobj that can be referenced in the
 top-level loop.  So why use this keyword argument?  Perhaps you would like to
 do your computation on several stobjs that are all congruent to a given stobj,
 @('st').  Then by using @(':non-executable t') to introduce @('st'), you avoid
 allocating memory for @('st') that you never intend to use.  Similarly, you
 can avoid allocating such memory when your intended use of @('st') is only as
 a local stobj (see @(see with-local-stobj)) or as the type of a stobj field of
 another stobj.  But see @(see add-global-stobj) and @(see remove-global-stobj)
 for utilities that change whether or not there is a global stobj for a given
 name.</p>")

(defxdoc defstobj-element-type
  :parents (defstobj)
  :short "Specify the element type for a @(see stobj) array field"
  :long "<p>This topic assumes familiarity with the @(tsee defstobj) event.  It
 documents the @(':element-type') keyword for a stobj array field.  Note that
 @(':element-type') is only supported for stobj array fields, not other sorts
 of stobj fields.</p>

 <p>Consider a stobj array field with @(':type') of the form @('(array
 etype (n))'), for example, @('(array bit (8))').  Logically, this
 &ldquo;array&rdquo; is a list, each of whose elements has the indicated type,
 @('etype') &mdash; in our example, the type, @('bit') (i.e., 0 or 1).  In raw
 Lisp, however, an array is allocated.  The Lisp code that allocates that array
 can specify the type of its elements, and may specify that element type to be
 @('bit').  But it would also be legal to specify a weaker type.  In particular,
 the type @('t') is a legal type for every object, and this can be specified by
 including @(':element-type t') in your stobj array field.</p>

 <p>Perhaps surprisingly, Lisp code may run faster when the element type in a
 raw Lisp array is @('t') rather than a more restrictive type.  The
 @(':element-type') of a stobj array field may be specified to be @('t') to
 give this behavior, by using @(':element-type t').  You can do your own
 experiments to decide whether that is helpful, in particular by considering
 @(see community-book) @('books/demos/element-type.lisp').  That file starts
 with the following events and then times reading and writing the stobj
 array.</p>

 @({
 (defconst *ar-size* (expt 10 8))
 (defstobj st1
   (ar1 :type (array double-float (*ar-size*))
        :element-type t ; Omit this line to compare times with or without it.
        :initially 0)
 ; Optional:
   :inline t)
 })

 <p>Our own experiments with this file have produced the following results (for
 both realtime and runtime) with CCL and SBCL on a 2019-era MacBook Pro (2.4
 GHz 8-Core Intel Core i9).  They suggest the use of @(':element-type t') with
 read-intensive applications when using CCL.  Results may be very different
 without the use of @(':inline t'), and of course these results may not be
 indicative of your own experience with various applications, Lisps, and
 operating systems.</p>

 @({
 (time$ (reads-st1 st1 *ar-size*))
 Results:
   CCL
     With :element-type t
       0.27 seconds (32 bytes allocated)
     Without :element-type t
     ; 0.47 seconds (32 bytes allocated)
   SBCL
     With :element-type t
       0.23 seconds (0 bytes allocated)
     Without :element-type t
       0.21 seconds (0 bytes allocated)

 (time$ (writes-st1 st1 (to-df 2) *ar-size*))
 Results:
   CCL
     With :element-type t
       1.17 seconds (128 bytes allocated);
     Without :element-type t
       0.27 seconds (128 bytes allocated)
   SBCL
     With :element-type t
       0.24 seconds realtime (0 bytes allocated)
     Without :element-type t
       0.25 seconds (0 bytes allocated).
 })

 <p>Currently the legal values for @(':element-type') are @('t') and the
 default value, which is the element type specified in the @(':type') field of
 the stobj array field specification.  This could change if experiments suggest
 something different.</p>")

(defxdoc defstub
  :parents (events)
  :short "Stub-out a function symbol"
  :long "@({
 Examples:
 ACL2 !>(defstub subr1 (* * state) => (mv * state))
 ACL2 !>(defstub add-hash (* * hashtable) => hashtable)
 ACL2 !>(defstub inv (*) => * :formals (x) :guard (fieldp x))

 General Forms:
 (defstub name (i1 ... ik) => outputs :kwd1 val1 ... :kwdn valn) ; new style
 (defstub name (i1 ... ik) outputs :kwd1 val1 ... :kwdn valn)    ; old style
 })

 <p>where @('name') is a new function symbol, and @('(i1 ... ik)'),
 @('outputs'), @(':kwdi'), and @('vali') must be as follows, respectively.</p>

 <ul>

 <li><i>New style:</i> @('((name i1 ... ik) => outputs :kwd1 val1 ... :kwdn
 valn)') is a valid new-style @(see signature).</li>

 <li><i>Old style:</i> @('(name (i1 ... ik) outputs :kwd1 val1 ... :kwdn
 valn)') is a valid old-style @(see signature).</li>

 </ul>

 <p>Also see @(see signature).  Note that @('(i1 ... ik)') is the
 list of formal parameters of the newly-defined function symbol, @('name').</p>

 <p>Note that while the @('defstub') syntax resembles a @(see signature), it is
 different: @('name') occurs outside the parentheses containing @('(i1
 ... ik)') in the @('defstub') syntax, but inside in the signature syntax.</p>

 <p>A @('defstub') macro call expands into an @(tsee encapsulate) event (see
 @(see encapsulate)).  Thus, no axioms are available about @('name') but it may
 be used wherever a function of the given signature is permitted.  Exception:
 if @('outputs') is of the form @('(mv ...)'), then a @(':')@(tsee
 type-prescription) rule is introduced stating that @('name') returns a value
 satisfying @(tsee true-listp).</p>")

(defxdoc deftheory
  :parents (events theories)
  :short "Define a theory (to @(see enable) or @(see disable) a set of rules)"
  :long "@({
 Example:
 (deftheory interp-theory
            (set-difference-theories
              (universal-theory :here)
              (universal-theory 'interp-section)))

 General Forms:
 (deftheory name term)
 (deftheory name term :redundant-okp flg)
 })

 <p>where @('name') is a new symbolic name (see @(see name)), @('term') is a
 term that when evaluated will produce a theory (see @(see theories)), and
 @('flg') is expected to be Boolean.  Except for the variable @(tsee world),
 @('term') must contain no free variables.  @('Term') is evaluated with @(tsee
 world) bound to the current world (see @(see world)) and the resulting theory
 is then converted to a <i>runic theory</i> (see @(see theories)) and
 associated with @('name').  Henceforth, this runic theory is returned as the
 value of the theory expression @('(theory name)').</p>

 <p>The value returned is the length of the resulting theory.  For example, in
 the following, the theory associated with @(''FOO') has 60 @(see rune)s as of
 ACL2 Version  8.6:</p>

 @({
  ACL2 !>(deftheory foo (union-theories '(binary-append)
                                        (theory 'minimal-theory)))

  Summary
  Form:  ( DEFTHEORY FOO ...)
  Rules: NIL
  Time:  0.01 seconds (prove: 0.00, print: 0.00, other: 0.01)
   60
  ACL2 !>
 })

 <p>Note that the theory being defined depends on the context.  For example,
 consider the following (contrived) example book.</p>

 @({
    (in-package "ACL2")
    (defund foo (x) (consp x)) ; defund disables foo
    (local (in-theory (enable foo)))
    (deftheory my-theory (current-theory :here))
    (in-theory (disable foo))
    (defthm foo-property
      (implies (consp x)
               (foo x))
      :hints (("Goal" :in-theory (enable my-theory))))
 })

 <p>At the time @('foo-property') is proved admissible during book
 certification (see @(see certify-book)), the @(tsee local) @(tsee in-theory)
 event has previously been evaluated, so the @(see definition) of @('foo') is
 @(see enable)d.  Thus, the @(':in-theory') hint on @('foo-property') will
 @(see enable) @('foo'), and the theorem proves.  HOWEVER, when the book is
 later included (see @(see include-book)), the @(tsee local) event is skipped,
 so the definition of @('foo') is @(see disable)d at the time the @(see theory)
 @('my-theory') is defined.  Hence, unlike the case for the admissibility pass
 of the book's certification, that theory does not include the definition of
 @('foo') when the book is included.</p>

 <p>There is, however, a way to ensure that a @(see theory) defined in a book
 is the same at @(tsee include-book) time as it was during the admissibility
 pass of the book's certification; see @(see deftheory-static).</p>

 <p>Note that a @('deftheory') event is never redundant unless
 @(':redundant-okp t') is specified, which supports a limited form of
 redundancy.  See @(see redundant-events).</p>")

(defxdoc deftheory-static
  :parents (events theories)
  :short "Define a `static' theory (to @(see enable) or @(see disable) a set of rules)"
  :long "<p>This macro provides a variant of @(tsee deftheory), such that the
 resulting theory is the same at @(tsee include-book) time as it was at @(tsee
 certify-book) time.</p>

 <p>We assume that the reader is familiar with @(see theories); see @(see
 deftheory).  We begin here by illustrating how @('deftheory-static') differs
 from @(tsee deftheory).  Suppose for example that the following events are the
 first two events in a book, where that book is certified in the initial ACL2
 @(see world) (see @(see ground-zero)).</p>

 @({
  (deftheory my-theory
    (current-theory :here))
  (deftheory-static my-static-theory
    (current-theory :here))
 })

 <p>Now suppose we include that book after executing the following event.</p>

 @({
  (in-theory (disable car-cons))
 })

 <p>Suppose that later we execute @('(in-theory (theory 'my-theory))').  Then
 the rule @('car-cons') will be disabled, because it was disabled at the time
 the expression @('(current-theory :here)') was evaluated when processing the
 @('deftheory') of @('my-theory') while including the book.  However, if we
 execute @('(in-theory (theory 'my-static-theory))'), then the rule
 @('car-cons') will be enabled, because the value of the theory
 @('my-static-theory') was saved at the time the book was certified.</p>

 @({
  General Form:
  (deftheory-static name term)
 })

 <p>The arguments are handled the same as for @(tsee deftheory).  Thus,
 @('name') is a new symbolic name (see @(see name)), and @('term') is a term
 that when evaluated will produce a theory (see @(see theories)).  Except for
 the variable @(tsee world), @('term') must contain no free variables.
 @('Term') is evaluated with @(tsee world) bound to the current world (see
 @(see world)) and the resulting theory is then converted to a <i>runic
 theory</i> (see @(see theories)) and associated with @('name').  Henceforth,
 this runic theory is returned as the value of the theory expression @('(theory
 name)').</p>

 <p>As for @(tsee deftheory), the value returned is the length of the resulting
 theory.</p>

 <p>We conclude with an optional discussion about the implementation of
 @('deftheory-static'), for those familiar with @(tsee make-event).  The
 following macroexpansion of the @('deftheory-static') form above shows how
 this works (see @(see trans1)).</p>

 @({
  ACL2 !>:trans1 (deftheory-static my-static-theory
                   (current-theory :here))
   (MAKE-EVENT (LET ((WORLD (W STATE)))
                    (LIST 'DEFTHEORY
                          'MY-STATIC-THEORY
                          (LIST 'QUOTE (CURRENT-THEORY :HERE)))))
  ACL2 !>
 })

 <p>The idea is that upon evaluation of this @('make-event') form, the first
 step is to evaluate the indicated @(tsee LET) expression to obtain a form
 @('(deftheory my-theory '(...))'), where ``@('(...)')'' is a list of all @(see
 rune)s in current theory.  If this form is in a book being certified, then the
 resulting @('deftheory') form is stored in the book's certificate, and is used
 when the book is included later.</p>")

(defxdoc defthm
  :parents (events)
  :short "Prove and name a theorem"
  :long "@({
  Examples:
  (defthm assoc-of-app
          (equal (app (app a b) c)
                 (app a (app b c))))
 })

 <p>The following nonsensical example illustrates all the optional arguments
 but is illegal because not all combinations are permitted.  See @(see hints)
 for a complete list of @(see hints).</p>

 @({
  (defthm main
          (implies (hyps x y z) (concl x y z))
         :rule-classes (:REWRITE :GENERALIZE)
         :instructions (induct prove promote (dive 1) x
                               (dive 2) = top (drop 2) prove)
         :hints (("Goal"
                  :do-not '(generalize fertilize)
                  :in-theory (set-difference-theories
                               (current-theory :here)
                               '(assoc))
                  :induct (and (nth n a) (nth n b))
                  :use ((:instance assoc-of-append
                                   (x a) (y b) (z c))
                        (:functional-instance
                          (:instance p-f (x a) (y b))
                          (p consp)
                          (f assoc)))))
         :otf-flg t)

  General Form:
  (defthm name term
          :rule-classes rule-classes
          :instructions instructions
          :hints        hints
          :otf-flg      otf-flg)
 })

 <p>where @('name') is a new symbolic name (see @(see name)), @('term') is a
 term alleged to be a theorem, and @(tsee rule-classes), @(tsee instructions),
 @(tsee hints), and @(tsee otf-flg) are as described in their respective @(see
 documentation).  The keyword arguments above are all optional, however you may
 not supply both @(':')@(tsee instructions) and @(':')@(tsee hints), since one
 drives the interactive @(see proof-builder) and the other drives the theorem
 prover.  If @(':')@(tsee rule-classes) is not specified, the list
 @('(:rewrite)') is used; if you wish the theorem to generate no rules, specify
 @(':')@(tsee rule-classes) @('nil').</p>

 <p>When ACL2 processes a @('defthm') event, it first tries to prove the @(see
 term) using the indicated hints (see @(see hints)) or @(see instructions) (see
 @(see proof-builder)).  If it is successful, it stores the rules described by
 the rule-classes (see @(see rule-classes)), proving the necessary
 corollaries.</p>")

(defxdoc defthmd
  :parents (defthm events)
  :short "Prove and name a theorem and then disable it"
  :long "<p>Use @('defthmd') instead of @(tsee defthm) when you want to disable
 a theorem immediately after proving it.  This macro has been provided for
 users who prefer working in a mode where theorems are only enabled when
 explicitly directed by @(':')@(tsee in-theory).  Specifically, the form</p>

 @({
  (defthmd NAME TERM ...)
 })

 <p>expands to the following, except that some output is inhibited for the
 @(tsee in-theory) and @(tsee value-triple) @(see events):</p>

 @({
  (progn
    (defthm NAME TERM ...)
    (in-theory (disable NAME))
    (value-triple '(:defthmd NAME))).
 })

 <p>@('Defthmd') events are generally not redundant, because the generated
 @(tsee in-theory) event is not redundant.  This default can be changed; see
 @(see set-in-theory-redundant-okp).</p>

 <p>See @(see defthm) for documentation of @('defthm').</p>")

(defxdoc defthy
  :parents (events theories deftheory)
  :short "Define a theory (to @(see enable) or @(see disable) a set of rules)"
  :long "<p>See @(see deftheory).  The @('defthy') macro is simply a convenient
 macro for @('deftheory') that supports a limited notion of redundancy; see
 @(see redundant-events).  Specifically: a call @('(defthy name expr)') expands
 to the corresponding event @('(deftheory name expr :redundant-okp t)').</p>")

(defxdoc defttag
  :parents (interfacing-tools events)
  :short "Introduce a trust tag (ttag)"
  :long "<p><b>Introduction</b>.  This event is intended for advanced users
 who, in essence, want to build extensions of ACL2.  The typical intended use
 is to create @(see books) that extend the functionality of ACL2 in ways not
 allowed without a so-called ``active trust tag''.  A trust tag thus represents
 a contract: The writer of such a book is guaranteeing that the book extends
 ACL2 in a ``correct'' way as defined by the writer of the book.  The writer of
 the book will often have a small section of the book in the scope of an active
 trust tag that can be inspected by potential users of that book:</p>

 @({
  <initial part of book, which does not use trust tags>
  (defttag :some-ttag) ; install :some-ttag as an active trust tag
  <various code that requires an active trust tag>
  (defttag nil)        ; remove active trust tag
  <final part of book, which does not use trust tags>
 })

 <p>Why might trust tags be needed?  The evaluation of certain functions can
 introduce bugs and even unsoundness, but can be useful in restricted ways that
 avoid such issues.  For example, @(tsee sys-call) can be used in an unsafe
 way, for example to overwrite files, or worse; see @(see sys-call) for a
 frightening example from Bob Boyer.  The following example shows that the
 function @(tsee sys-call) is restricted by default, but can be called after
 installing an active trust tag.</p>

 @({
  ACL2 !>(sys-call "pwd" nil)

  ACL2 Error in TOP-LEVEL:  The SYS-CALL function cannot be called unless
  a trust tag is in effect.  See :DOC defttag.

  ACL2 !>(defttag t) ; Install :T as an active trust tag.

  TTAG NOTE: Adding ttag :T from the top level loop.
   T
  ACL2 !>(sys-call "pwd" nil) ; print the current directory and return NIL
  /u/kaufmann
  NIL
  ACL2 !>(defttag nil) ; Remove the active trust tag (using value NIL).
   NIL
  ACL2 !>(sys-call "pwd" nil) ; Now we get the error again:

  ACL2 Error in TOP-LEVEL:  The SYS-CALL function cannot be called unless
  a trust tag is in effect.  See :DOC defttag.

  ACL2 !>
 })

 <p>Of course, using @(tsee sys-call) with the Linux command @('pwd') is not
 likely to cause any soundness problems!  So suppose we want to create a
 function that prints the working directory.  We might put the following @(see
 events) into a book that is to be certified.</p>

 @({
  (in-package "ACL2")
  (defttag :pwd-ttag)
  (defun print-working-dir ()
    (declare (xargs :mode :program))
    (sys-call "pwd" nil))
  (defttag nil) ; optional (books end with this implicitly)
 })

 <p>We can certify this book with a specification that @(':pwd-ttag') is a
 legal trust tag:</p>

 @({
  (certify-book "pwd" 0 t :ttags (:pwd-ttag))
 })

 <p>One can now use this book by executing @(tsee include-book) with keyword
 parameter @(':ttags (:pwd-ttag)') and then calling function
 @('print-working-dir'):</p>

 @({
  (include-book "pwd" :ttags (:pwd-ttag))
  (print-working-dir) ; working directory is printed to terminal
 })

 <p><b>Detailed documentation.</b></p>

 @({
  General Form:
  (defttag tag-name)
 })

 <p>where @('tag-name') is a symbol.</p>

 <p>Note however that if @('tag-name') is not @('nil'), then it is converted to
 a ``corresponding @(see keyword)'': a symbol in the @('"KEYWORD"') package
 with the same @(tsee symbol-name) as @('tag-name').  Thus, for example,
 @('(defttag foo)') is equivalent to @('(defttag :foo)').  Moreover, a
 non-@('nil') symbol with a @(tsee symbol-name) of @('"NIL"') is illegal for
 trust tags; thus, for example, @('(defttag :nil)') is illegal.</p>

 <p>This event introduces or removes a so-called active trust tag (or ``ttag'',
 pronounced ``tee tag'').  An active ttag is a @(see keyword) symbol that is
 associated with potentially unsafe evaluation.  For example, calls of @(tsee
 sys-call) are illegal unless there is an active trust tag.  An active trust
 tag can be installed using a @('defttag') event.  If one introduces an active
 ttag and then writes definitions that contain calls of @(tsee sys-call),
 presumably in a defensibly ``safe'' way, then responsibility for those calls
 is attributed to that ttag.  This attribution (or blame!) is at the level of
 @(see books); a book's @(see certificate) contains a list of ttags that are
 active in that book, or in a book that is included (possibly @(see local)ly),
 or in a book included in a book that is included (either inclusion being
 potentially @(see local)), and so on.  We explain all this in more detail
 below.</p>

 <p>@('(Defttag :tag-name)') is essentially equivalent to</p>

 @({
  (table acl2-defaults-table :ttag :tag-name)
 })

 <p>and hence is @(tsee local) to any @(see books) and @(tsee encapsulate)
 @(see events) in which it occurs; see @(see acl2-defaults-table).  We say more
 about the scope of @('defttag') forms below.</p>

 <p>Note: This is an event!  It does not print the usual event @(see summary)
 but nevertheless executes the above @(tsee table) event and hence changes the
 ACL2 logical @(see world), and is so recorded.  Although no event summary is
 printed, it is important to note that the ``TTAG NOTE'', discussed below, is
 always printed for a non-nil @(':tag-name') (unless deferred; see @(see
 set-deferred-ttag-notes)).</p>

 <p><b>Active ttags.</b> Suppose @('tag-name') names a non-@('nil') symbol.
 Then @('(defttag :tag-name)') sets @(':tag-name') to be the (unique) ``active
 ttag.''  There must be an active ttag in order for there to be any mention of
 certain functions, including @(tsee sys-call); evaluate the form
 @('(strip-cars *ttag-fns*)') to see the full list of such symbols.  The macro
 @(tsee progn!)  similarly requires an active ttag.  On the other hand,
 @('(defttag nil)') removes the active ttag, if any; there is then no active
 ttag.  The scope of a @('defttag') form in a book being certified or included
 is limited to subsequent forms in the same book before the next
 @('defttag') (if any) in that book.  Similarly, if a @('defttag') form is
 evaluated in the top-level loop, then its effect is limited to subsequent
 forms in the top-level loop before the next @('defttag') in the top-level
 loop (if any).  Moreover, @(tsee certify-book) is illegal when a ttag is
 active; of course, in such a circumstance one can execute @('(defttag nil)')
 in order to allow book certification.</p>

 <p><b>Ttag notes and the ``certifier.''</b> When a @('defttag') is executed
 with an argument other than @('nil'), output is printed, starting on a fresh
 line with: @('TTAG NOTE').  For example:</p>

 @({
  ACL2 !>(defttag :foo)

  TTAG NOTE: Adding ttag :FOO from the top level loop.
   :FOO
  ACL2 !>
 })

 <p>If the @('defttag') occurs in an included book, the message looks like
 this.</p>

 @({
  TTAG NOTE (for included book): Adding ttag :FOO from file /u/smith/acl2/my-book.lisp.
 })

 <p>The ``@('TTAG NOTE')'' message is always printed on a single line.  The
 intention is that one can search the standard output for all such notes in
 order to find all <i>defttag</i> events.  In a sense, <i>defttag</i> events
 can allow you to define your own system on top of ACL2 (for example, see @(see
 progn!)).  So in order for someone else (who we might call the ``certifier'')
 to be confident that your collection of @(see books) is meaningful, that
 certifier should certify all the user-supplied books from scratch and check
 either that no @(':ttags') were supplied to @(tsee certify-book), or else look
 for every @('TTAG NOTE') in the standard output in order to locate all
 @('defttag') @(see events) with non-@('nil') tag name.  In this way, the
 certifier can in principle decide whether to be satisfied that those
 @('defttag') events did not allow inappropriate forms in the user-supplied
 books.</p>

 <p>In order to eliminate much of the output from @('TTAG NOTE')s, see @(see
 set-deferred-ttag-notes).  Note however that the resulting security is
 somewhat less; therefore, a @('TTAG NOTE') is printed when invoking
 @('set-deferred-ttag-notes') to defer printing of ttag notes.</p>

 <p><b>Allowed ttags when certifying and including books.</b> A @('defttag')
 form may not be evaluated unless its argument is a so-called ``allowed'' ttag.
 All ttags are allowed in the interactive top-level loop.  However, during
 @(tsee certify-book) and @(tsee include-book), the set of allowed ttags may be
 restricted according to the @(':ttags') keyword argument.  If this argument is
 @('nil') then no ttag is allowed, so a @('defttag') call will fail during book
 certification or inclusion in this case.  This restriction applies even to
 @('defttag') forms already evaluated in the so-called certification @(see
 world) at the time @(tsee certify-book) is called.  But note that @('(defttag
 nil)') is always legal.</p>

 <p>A @(':ttags') argument of @(tsee certify-book) and @(tsee include-book) can
 have value @(':all'), indicating that every ttag is allowed, i.e., no
 restriction is being placed on the arguments, just as in the interactive
 top-level loop.  In the case of @('include-book'), an omitted @(':ttags')
 argument or an argument of @(':default') is treated as @(':all'), except that
 warnings will occur when the book's @(see certificate) includes ttags; but for
 @('certify-book'), an omitted @('ttags') argument is treated as @('nil').
 Otherwise, if the @(':ttags') argument is supplied but not @(':all'), then its
 value is a true list of ttag specifications, each having one of the following
 forms, where @('sym') is a non-@('nil') symbol which is treated as the
 corresponding @(see keyword).</p>

 <blockquote>

 <p>(1) @(':sym')</p>

 <p>(2) @('(:sym)')</p>

 <p>(3) @('(:sym x1 x2 ... xk)'), where k &gt; 0 and each @('xi') is a string,
 except that one @('xi') may be @('nil').</p></blockquote>

 <p>In Case (1), @('(defttag :sym)') is allowed to occur in at most one book or
 else in the top-level loop (i.e., the certification world for a book under
 certification or a book being included).  Case (2) allows @('(defttag :sym)')
 to occur in an unlimited number of books.  For case (3) the @('xi') specify
 where @('(defttag :sym)') may occur, as follows.  The case that @('xi') is
 @('nil') refers to the top-level loop, while all other @('xi') are filenames,
 where the @('".lisp"') extension is optional and relative pathnames are
 considered to be relative to the connected book directory (see @(see cbd)).
 Note that the restrictions on @('(defttag :sym)') apply equally to any
 equivalent for based on the notion of ``corresponding keyword'' discussed
 above, e.g., @('(defttag acl2::sym)').</p>

 <p>An error message, as shown below, illustrates how ACL2 enforces the notion
 of allowed ttags.  Suppose that you call @(tsee certify-book) with argument
 @(':ttags (:foo)'), where you have already executed @('(defttag :foo)') in the
 certification world (i.e., before calling @(tsee certify-book)).  Then ACL2
 immediately associates the ttag @(':foo') with @('nil'), where again, @('nil')
 refers to the top-level loop.  If ACL2 then encounters @('(defttag foo)')
 inside that book, you will get the following error (using the book's absolute
 pathname, as shown):</p>

 @({
  ACL2 Error in ( TABLE ACL2-DEFAULTS-TABLE ...):  The ttag :FOO associated
  with file /u/smith/work/my-book.lisp is not among the set of ttags permitted
  in the current context, specified as follows:
    ((:FOO NIL)).
  See :DOC defttag.
 })

 <p>In general the structure displayed by the error message, which is @('((:FOO
 NIL))') in this case, represents the currently allowed ttags with elements as
 discussed in (1) through (3) above.  In this case, that list's unique element
 is @('(:FOO NIL)'), meaning that ttag @(':FOO') is only allowed at the top
 level (as represented by @('NIL')).</p>

 <p><b>Associating ttags with books and with the top-level loop.</b> When a
 book is certified, each form @('(defttag tag)') that is encountered for
 non-@('nil') @('tag') in that book or an included book is recorded in the
 generated @(see certificate), which associates the keyword corresponding to
 @('tag') with the @(see full-book-name) of the book containing that
 @('defttag').  If such a @('defttag') form is encountered outside a book, hence
 in the @(see portcullis) of the book being certified or one of its included
 books, then that keyword is associated with @('nil') in the generated @(see
 certificate).  Note that the notion of ``included book'' here applies to the
 recursive notion of a book either included directly in the book being
 certified or else included in such a book, where we account even for @(see
 local)ly included books.</p>

 <p>For examples of ways to take advantage of ttags, see @(see hacker), @(see
 include-raw), @(see quicklisp), and more generally @(see interfacing-tools).
 See also @(see ttags-seen), @(see progn!), @(see remove-untouchable), @(see
 set-raw-mode), and @(see sys-call).</p>")

(defxdoc defun
  :parents (events programming)
  :short "Define a function symbol"
  :long "@({
  Examples:
  (defun app (x y)
    (if (consp x)
        (cons (car x) (app (cdr x) y))
        y))

  (defun fact (n)
    (declare (xargs :guard (and (integerp n)
                                (>= n 0))))
    (if (zp n)
        1
        (* n (fact (1- n)))))

  General Form:
  (defun fn (var1 ... varn)
    dcl ... dcl ; optionally, also one documentation string; see below
    body)
 })

 <p>where @('fn') is the symbol you wish to define and is a new symbolic name
 (see @(see name)), @('(var1 ... varn)') is its list of formal parameters (see
 @(see name)), and @('body') is its body.  The definitional axiom is logically
 admissible provided certain restrictions are met.  These are sketched
 below.</p>

 <p>See also @(see mutual-recursion) for how to use @('defun') to make mutually
 recursive definitions, including discussion of how the @(tsee xargs) @(see
 declaration)s in one @('defun') may affect the other definitions.</p>

 <p>Note that ACL2 does not support the use of @('lambda-list') keywords (such
 as @('&optional')) in the formals list of functions.  We do support some such
 keywords in macros and often you can achieve the desired syntax by defining a
 macro in addition to the general version of your function.  See @(see
 defmacro).</p>

 <p>The <i>declarations</i> (see @(see declare)), @('dcl'), are optional.  If
 more than one @('dcl') form appears, they are effectively grouped together as
 one.  Perhaps the most commonly used ACL2 specific declaration is of the form
 @('(declare (xargs :guard g :measure m))').  This declaration in the
 @('defun') of some function @('fn') has the effect of making the ``@(see
 guard)'' for @('fn') be the term @('g') and the ``measure'' be the term
 @('m').  The notion of ``measure'' is crucial to ACL2's definitional
 principle.  The notion of ``guard'' is not, and is discussed elsewhere; see
 @(see verify-guards) and see @(see set-verify-guards-eagerness).  Note that a
 @(':measure') is not allowed for a non-recursive definition unless it is part
 of a @(tsee mutual-recursion) (exception: a measure of @('nil') is treated as
 though the @('measure') was omitted); moreover, if a @(':measure') is
 supplied, then it must be a legal term.  Apart from these restrictions, the
 @(':measure') is ignored in @(':')@(tsee program) mode; see @(see
 defun-mode).</p>

 <p>One documentation string may be included between the list of formal
 parameters and the body, but it is essentially ignored by ACL2.  See @(see
 documentation) for a discussion of documentation in ACL2.</p>

 <p>We now briefly discuss the ACL2 definitional principle, using the following
 definition form which is offered as a more or less generic example.</p>

 @({
  (defun fn (x y)
    (declare (xargs :guard (g x y)
                    :measure (m x y)))
    (if (test x y)
        (stop x y)
      (step (fn (d x) y))))
 })

 <p>Note that in our generic example, @('fn') has just two arguments, @('x')
 and @('y'), the @(see guard) and measure terms involve both of them, and the
 body is a simple case split on @('(test x y)') leading to a ``non-recursive''
 branch, @('(stop x y)'), and a ``recursive'' branch.  In the recursive branch,
 @('fn') is called after ``decrementing'' @('x') to @('(d x)') and some step
 function is applied to the result.  Of course, this generic example is quite
 specific in form but is intended to illustrate the more general case.</p>

 <p>Provided this definition is admissible under the logic, as outlined below,
 it adds the following axiom to the logic.</p>

 @({
  Defining Axiom:
  (fn x y)
    =
  (if (test x y)
      (stop x y)
    (step (fn (d x) y)))
 })

 <p>Note that the @(see guard) of @('fn') has no bearing on this logical
 axiom.</p>

 <p>This defining axiom is actually implemented in the ACL2 system by a
 @(':')@(tsee definition) rule, namely</p>

 @({
  (equal (fn x y)
         (if (test a b)
             (stop a b)
           (step (fn (d a) b)))).
 })

 <p>See @(see definition) for a discussion of how definition rules are applied.
 Roughly speaking, the rule causes certain instances of @('(fn x y)') to be
 replaced by the corresponding instances of the body above.  This is called
 ``opening up'' @('(fn x y)').  The instances of @('(fn x y)') opened are
 chosen primarily by heuristics which determine that the recursive calls of
 @('fn') in the opened body (after simplification) are more desirable than the
 unopened call of @('fn').</p>

 <p>This discussion has assumed that the definition of @('fn') was admissible.
 Exactly what does that mean?  First, @('fn') must be a previously
 unaxiomatized function symbol (however, see @(see ld-redefinition-action)).
 Second, the formal parameters must be distinct variable names.  Third, the
 @(see guard), measure, and body should all be terms and should mention no free
 variables except the formal parameters.  Thus, for example, body may not
 contain references to ``global'' or ``special'' variables; ACL2 constants or
 additional formals should be used instead.</p>

 <p>The final conditions on admissibility concern the termination of the
 recursion.  Roughly put, all applications of @('fn') must terminate.  In
 particular, there must exist a binary relation, @('rel'), and some unary
 predicate @('mp') such that @('rel') is well-founded on objects satisfying
 @('mp'), the measure term @('m') must always produce something satisfying
 @('mp'), and the measure term must decrease according to @('rel') in each
 recursive call, under the hypothesis that all the tests ruling the call are
 satisfied (see @(see rulers)).  By the meaning of well-foundedness, we know
 there are no infinitely descending chains of successively @('rel')-smaller
 @('mp')-objects.  Thus, the recursion must terminate.</p>

 <p>The default well-founded relation is @(tsee o<), an ``ordinal less-than''
 relation (discussed further below) that reduces to ordinary @('<') on the
 natural numbers.  The default measure term is @('(acl2-count var)'), where
 @('var') is a formal parameter that is chosen heuristically: roughly speaking,
 it is the first formal that is tested along every branch and changed in each
 recursive call.</p>

 <p>The only primitive well-founded relation in ACL2 is @(tsee o<), which is
 known to be well-founded on the @(tsee o-p)s.  For the proof of
 well-foundedness, see @(see proof-of-well-foundedness).  However it is
 possible to add new well-founded relations.  For details, see @(see
 well-founded-relation).  We discuss later how to specify which well-founded
 relation is selected by @('defun') and in the present discussion we assume,
 without loss of generality, that it is @(tsee o<) on the @(tsee o-p)s.</p>

 <p>For example, for our generic definition of @('fn') above, with measure term
 @('(m x y)'), two theorems must be proved.  The first establishes that @('m')
 produces an ordinal:</p>

 @({
  (o-p (m x y)).
 })

 <p>The second shows that @('m') decreases in the (only) recursive call of
 @('fn'):</p>

 @({
  (implies (not (test x y))
           (o< (m (d x) y) (m x y))).
 })

 <p>Observe that in the latter formula we must show that the ``@('m')-size'' of
 @('(d x)') and @('y') is ``smaller than'' the @('m')-size of @('x') and
 @('y'), provided the test, @('(test x y)'), in the body fails, thus leading to
 the recursive call @('(fn (d x) y)').</p>

 <p>See @(see o<) for a discussion of this notion of ``smaller than.''  It
 should be noted that the most commonly used ordinals are the natural numbers
 and that on natural numbers, @(tsee o<) is just the familiar ``less than''
 relation (@(tsee <)).  Thus, it is very common to use a measure @('m') that
 returns a nonnegative integer, for then @('(o-p (m x y))') becomes a simple
 conjecture about the type of @('m') and the second formula above becomes a
 conjecture about the less-than relationship of nonnegative integer
 arithmetic.</p>

 <p>The most commonly used measure function is @(tsee acl2-count), which
 computes a nonnegative integer size for all ACL2 objects.  See @(see
 acl2-count).</p>

 <p>Probably the most common recursive scheme in Lisp @(see programming) is
 when some formal is supposed to be a list and in the recursive call it is
 replaced by its @(tsee cdr).  For example, @('(test x y)') might be simply
 @('(atom x)') and @('(d x)') might be @('(cdr x)').  In that case,
 @('(acl2-count x)') is a suitable measure because the @(tsee acl2-count) of a
 @(tsee cons) is strictly larger than the @(tsee acl2-count)s of its @(tsee
 car) and @(tsee cdr).  Thus, ``recursion by @(tsee car)'' and ``recursion by
 @(tsee cdr)'' are trivially admitted if @(tsee acl2-count) is used as the
 measure and the definition protects every recursive call by a test insuring
 that the decremented argument is a @(tsee consp).  Similarly, ``recursion by
 @(tsee 1-)'' in which a positive integer formal is decremented by one in
 recursion, is also trivially admissible.  See @(see built-in-clause) to extend
 the class of trivially admissible recursive schemes.</p>

 <p>We now turn to the question of which well-founded relation @('defun') uses.
 It should first be observed that @('defun') must actually select both a
 relation (e.g., @(tsee o<)) and a domain predicate (e.g., @(tsee o-p)) on
 which that relation is known to be well-founded.  But, as noted elsewhere (see
 @(see well-founded-relation-rule)), every known well-founded relation has a
 unique domain predicate associated with it and so it suffices to identify
 simply the relation here.</p>

 <p>The @(tsee xargs) field of a @(tsee declare) permits the explicit
 specification of any known well-founded relation with the keyword
 @(':well-founded-relation').  An example is given below.  If the @(tsee xargs)
 for a @('defun') specifies a well-founded relation, that relation and its
 associated domain predicate are used in generating the termination conditions
 for the definition.</p>

 <p>If no @(':well-founded-relation') is specified, @('defun') uses the
 @(':well-founded-relation') specified in the @(tsee acl2-defaults-table).  See
 @(see set-well-founded-relation) to see how to set the default well-founded
 relation (and, implicitly, its domain predicate).  The initial default
 well-founded relation is @(tsee o<) (with domain predicate @(tsee o-p)).</p>

 <p>This completes the brief sketch of the ACL2 definitional principle.
 Optionally, see @(see rulers) for a more detailed discussion of the
 termination analysis and resulting proof obligations for admissibility, as
 well as a discussion of the relation to how ACL2 stores induction schemes.
 See @(see induction-coarse-v-fine-grained) for a discussion of how well-chosen
 rulers can affect the induction scheme.</p>

 <p>On very rare occasions ACL2 will seem to "hang" when processing a
 definition, especially if there are many subexpressions of the body whose
 function symbol is @(tsee if) (or which macroexpand to such an expression).
 In those cases you may wish to supply the following to @(tsee xargs):
 @(':normalize nil').  This is an advanced feature that turns off certain
 simplification of @(see definition) bodies and @(see guard)s; @(see
 normalize).</p>

 <p>When a @('defun') form is submitted, ACL2 sometimes computes and stores a
 @(see type-prescription) rule for the function.  See @(see
 type-prescription-debugging) for relevant discussion.</p>

 <p>The following example illustrates all of the available declarations, but it
 is completely nonsensical and it shows only a few of the many @(':xargs')
 keywords.  See @(see xargs) for a complete list of @(':xargs') keywords; also
 see @(see hints).</p>

 @({
  (defun example (x y z a b c i j)
    (declare (ignore a b c)
             (ignorable x y)
             (irrelevant c)
             (type integer i j)
             (optimize (safety 3))
             (xargs :guard (symbolp x)
                    :measure (- i j)
                    :hints (("Goal"
                             :do-not-induct t
                             :do-not '(generalize fertilize)
                             :expand ((assoc x a) (member y z))
                             :restrict ((<-trans ((x x) (y (foo x)))))
                             :hands-off (length binary-append)
                             :in-theory (set-difference-theories
                                          (current-theory :here)
                                          '(assoc))
                             :induct (and (nth n a) (nth n b))
                             :use ((:instance assoc-of-append
                                              (x a) (y b) (z c))
                                   (:functional-instance
                                     (:instance p-f (x a) (y b))
                                     (p consp)
                                     (f assoc)))))
                    :guard-hints (("Subgoal *1/3'"
                                   :use ((:instance assoc-of-append
                                                    (x a) (y b) (z c)))))
                    :mode :logic
                    :verify-guards nil
                    :type-prescription (natp (example x y z a b c i j))))
    (example-body x y z i j))
 })")

(defxdoc defun$
  :parents (defun events apply$)
  :short "Define a function symbol and generate a warrant"
  :long "<p>@('Defun$') is just a macro that expands to the obvious @(tsee
  defun) followed by @(tsee defwarrant).</p>")

(defxdoc defun-inline
  :parents (defun events)
  :short "Define a potentially inlined function symbol and associated macro"
  :long "<p>You may be able to improve performance by replacing an event
 @('(defun f ...)') with a corresponding event @('(defun-inline f ...)'), in
 order to encourage the host Lisp compiler to inline calls of @('f').</p>

 @({
  Example Form:
  (defun-inline lng (x)
    (declare (xargs :guard (true-listp x)))
    (if (endp x) 0 (1+ (lng (cdr x)))))

  General Form:
  (defun-inline fn (var1 ... varn)
    dcl ... dcl ; optionally, also one documentation string; as for defun
    body)
 })

 <p>satisfying the same requirements as in the General Form for @(tsee defun).
 The effect is to define a macro @('fn') and a function @('fn$inline') (i.e., a
 symbol in the same package as @('fn') but whose @(tsee symbol-name) has the
 suffix @('"$INLINE"')), such that each call of @('fn') expands to a call of
 the function symbol @('fn$inline') on the same arguments.  Moreover, @(tsee
 table) @(see events) are generated that allow the use of @('fn') in @(see
 theory) expressions to represent @('fn$inline') and that cause any
 untranslated (user-level) call of @('fn$inline') to be printed as the
 corresponding call of @('fn').  The documentation string is an optional string
 that can provide documentation but is essentially ignored by ACL2.</p>

 <p>A form @('(defun-inline f ...)') actually defines a function named
 @('f$inline') and a corresponding macro named @('f') whose calls expand to
 calls of @('f$inline'), while providing the illusion that there is just the
 ``function'' @('f').  For example, the Example Form above macroexpands in one
 step to the following form.</p>

 @({
  (progn (defmacro lng (non-stobj-var0)
           (list 'lng$inline non-stobj-var0))
         (add-macro-fn lng lng$inline)
         (defun lng$inline (x)
           (declare (xargs :guard (true-listp x)))
           (if (endp x) 0 (1+ (lng (cdr x))))))
 })

 <p>Note that the above call of @(tsee add-macro-fn) generates the
 aforementioned two table events (see @(see add-macro-fn)), which provide the
 illusion that we are just defining a function @('lng'), as you can see in the
 following log: @('lng') appears rather than @('lng$inline').</p>

 @({
  ACL2 !>(set-gag-mode nil)
  <state>
  ACL2 !>(thm (equal (lng (append x y))
                     (+ (lng x) (lng y)))
              :hints (("Goal" :in-theory (enable lng))))

  [.. output omitted ..]

  Subgoal *1/2
  (IMPLIES (AND (NOT (ENDP X))
                (EQUAL (LNG (APPEND (CDR X) Y))
                       (+ (LNG (CDR X)) (LNG Y))))
           (EQUAL (LNG (APPEND X Y))
                  (+ (LNG X) (LNG Y)))).

  [.. output omitted ..]
 })

 <p>Under the hood, ACL2 arranges that every function symbol with suffix
 @('"$INLINE"') is presented to the compiler as one whose calls we would
 prefer to inline.  Technically: the Common Lisp form @('(declaim (inline
 f$inline))') is generated for a function symbol @('f$inline') before that
 symbol's definition is submitted.  However, the Common Lisp spec explicitly
 avoids requiring that the compiler respect this @('declaim') form.
 Fortunately, Common Lisp implementations often do respect it.</p>

 <p>Also see @(see defund-inline), see @(see defun-notinline), and see @(see
 defund-notinline).</p>

 <p><i>Remarks</i>.</p>

 <p>(1) None of these macros (including @('defun-inline')) is supported for use
 inside a @(tsee mutual-recursion).</p>

 <p>(2) Every function symbol defined in ACL2 whose @(tsee symbol-name) has the
 suffix @('"$INLINE"') is proclaimed to be inline; similarly for
 @('"$NOTINLINE"') and notinline.  These suffix restrictions are explained in
 a comment in the ACL2 source definition of macro @('defun-inline').  Note that
 only the functions themselves are thus proclaimed, not their executable
 counterparts (also known as *1* functions; see @(see evaluation)).</p>

 <p>(3) No special treatment for inlining (or notinlining) is given for
 function symbols locally defined by @(tsee flet), with two exceptions: when
 explicitly declared @('inline') or @('notinline') by the @('flet') form, and
 for symbols discussed in (1) and (2) above that, at some point in the current
 ACL2 session, were defined as function symbols in ACL2 (even if not currently
 defined because of undoing or being @(see local)).</p>

 <p>(4) The function symbol actually being defined by @('(defun-inline foo
 ...)')  is @('foo$inline').  As mentioned above, one can be oblivious to this
 fact when writing @(see theory) expressions or perusing prover output.
 However, for other purposes (for example, @(tsee verify-guards) and @(tsee
 defabsstobj) @(':exports')) you will need to supply the name of the function
 symbol rather than the name of the macro; e.g., for the above form
 @('(defun-inline foo ...)'), you may subsequently issue the event
 @('(verify-guards foo$inline)') but not @('(verify-guards foo)').</p>

 <p>(5) Obscure Remark.  Suppose that you certify a book with compilation (the
 default) in one host Lisp, saving the expansion file.  Suppose that you then
 compile in another host Lisp by using @(tsee include-book) with argument
 @(':load-compiled-file :comp').  Then in subsequent sessions, including that
 book with the second host Lisp will not result in any inline or notinline
 behavior for functions defined in the book.</p>")

(defxdoc defun-mode
  :parents (defun)
  :short "Determines whether a function definition is a logical act"
  :long "<p>Two ``@(see defun-mode)s'' are supported, @(':')@(tsee program) and
 @(':')@(tsee logic).  Roughly speaking, @(':')@(tsee program) mode allows you
 to prototype a function for execution without any proof burdens, while
 @(':')@(tsee logic) mode allows you to add a new definitional axiom to the
 logic.  The system comes up in @(':')@(tsee logic) mode.  Execution of
 functions whose @(see defun-mode) is @(':')@(tsee program) may render ACL2
 unsound!  See @(see defun-mode-caveat).</p>

 <p>Note that calls of @(tsee local) and of many @(see events) are skipped in
 @(':program') mode; see @(see program).</p>

 <p>When you define a function in the ACL2 logic, that function can be run on
 concrete data.  But it is also possible to reason deductively about the
 function because each definition extends the underlying logic with a
 definitional axiom.  To ensure that the logic is sound after the addition of
 this axiom, certain restrictions have to be met.  One restriction is that
 every function called by the newly defined one must be in @(':logic') mode.
 (However, see @(see defun-mode-lambdas) for some clarification concerning
 @(tsee apply$).)  But the most challenging restriction is that the system must
 prove that the recursion in the new definition terminates.</p>

 <p>Because ACL2 is a @(see programming) language, you often may wish simply to
 program in ACL2.  For example, you may wish to define your system and test it,
 without any logical burden.  Or, you may wish to define ``utility'' functions
 &mdash; functions that are executed to help manage the task of building your
 system but functions whose logical properties are of no immediate concern.
 Such functions might be used to generate test data or help interpret the
 results of tests.  They might create files or explore the ACL2 database.  The
 termination arguments for such functions are an unnecessary burden provided no
 axioms about the functions are ever used in deductions.</p>

 <p>Thus, ACL2 introduces the idea of the ``@(see defun-mode)'' of a function.
 The @(':mode') keyword of @(tsee defun)'s @(tsee declare) @('xarg') allows you
 to specify the @(see defun-mode) of a given definition.  If no @(':mode')
 keyword is supplied, the default @(see defun-mode) is used; see @(see
 default-defun-mode).</p>

 <p>There are two @(see defun-mode)s, each of which is written as a
 keyword:</p>

 <p>@(':')@(tsee program) &mdash; logically undefined but executable outside
 deductive contexts.</p>

 <p>@(':')@(tsee logic) &mdash; axiomatically defined as per the ACL2
 definitional principle.</p>

 <p>It is possible to change the @(see defun-mode) of a function from
 @(':')@(tsee program) to @(':')@(tsee logic).  We discuss this below.</p>

 <p>We think of functions having @(':')@(tsee program) mode as ``dangerous''
 functions, while functions having @(':')@(tsee logic) mode are ``safe.''  The
 only requirement enforced on @(':')@(tsee program) mode functions is the
 syntactic one: each definition must be well-formed ACL2.  Naively speaking, if
 a @(':')@(tsee program) mode function fails to terminate then no harm is done
 because no axiom is added (so inconsistency is avoided) and some invocations
 of the function may simply never return.  This simplistic justification of
 @(':')@(tsee program) mode execution is faulty because it ignores the damage
 that might be caused by ``mis-guarded'' functions.  See @(see
 defun-mode-caveat).</p>

 <p>We therefore implicitly describe an imagined implementation of @(see
 defun-mode)s that is safe and, we think, effective.  But please see @(see
 defun-mode-caveat).</p>

 <p>The default @(see defun-mode) is @(':')@(tsee logic).  This means that when
 you @(tsee defun) a function the system will try to prove termination.  If you
 wish to introduce a function of a different @(see defun-mode) use the
 @(':mode') @(tsee xargs) keyword.  Below we show @('fact') introduced as a
 function in @(':')@(tsee program) mode.</p>

 @({
  (defun fact (n)
    (declare (xargs :mode :program))
    (if (or (not (integerp n)) (= n 0))
        1
      (* n (fact (1- n)))))
 })

 <p>No axiom is added to the logic as a result of this definition.  By
 introducing @('fact') in @(':')@(tsee program) mode we avoid the burden of a
 termination proof, while still having the option of executing the function.
 For example, you can type</p>

 @({
  ACL2 !>(fact 3)
 })

 <p>and get the answer @('6').  If you type @('(fact -1)') you will get a hard
 lisp error due to ``infinite recursion.''</p>

 <p>However, the ACL2 theorem prover knows no axioms about @('fact').  In
 particular, if the term @('(fact 3)') arises in a proof, the theorem prover is
 unable to deduce that it is @('6').  From the perspective of the theorem
 prover it is as though @('fact') were an undefined function symbol of arity
 @('1').  Thus, modulo certain important issues (see @(see defun-mode-caveat)),
 the introduction of this function in @(':')@(tsee program) mode does not
 imperil the soundness of the system &mdash; despite the fact that the
 termination argument for @('fact') was omitted &mdash; because nothing of
 interest can be proved about @('fact').  Indeed, we do not allow @('fact') to
 be used in logical contexts such as conjectures submitted for proof.</p>

 <p>It is possible to convert a function from @(':')@(tsee program) mode to
 @(':')@(tsee logic) mode at the cost of proving that it is admissible.  This
 can be done by invoking</p>

 @({
  (verify-termination fact)
 })

 <p>which is equivalent to submitting the @(tsee defun) of @('fact'), again,
 but in @(':')@(tsee logic) mode.</p>

 @({
  (defun fact (n)
    (declare (xargs :mode :logic))
    (if (or (not (integerp n)) (= n 0))
        1
      (* n (fact (1- n)))))
 })

 <p>This particular event will fail because the termination argument requires
 that @('n') be nonnegative.  A repaired @(tsee defun), for example with @(tsee
 =) replaced by @(tsee <=), will succeed, and an axiom about @('fact') will
 henceforth be available.</p>

 <p>Technically, @(tsee verify-termination) submits a redefinition of the
 @(':')@(tsee program) mode function.  This is permitted, even when @(tsee
 ld-redefinition-action) is @('nil'), because the new definition is identical
 to the old (except for its @(':mode') and, possibly, other non-logical
 properties).</p>

 <p>See @(see guard) for a discussion of how to restrict the execution of
 functions.  @(see Guard)s may be ``verified'' for functions in @(':')@(tsee
 logic) mode; see @(see verify-guards).</p>")

(defxdoc defun-mode-caveat
  :parents (common-lisp)
  :short "Potential soundness issue for functions with @(see defun-mode)
  @(':')@(tsee program)"
  :long "<p>See @(see raw-lisp-error) for a general discussion of raw Lisp
 errors.  Although the discussion below focuses on raw Lisp errors that arise
 from calls of @(':')@(tsee program) mode functions, the soundness concerns
 expressed below apply to all raw Lisp errors.</p>

 <p>Technically speaking, in the current implementation, the execution of
 functions having @(see defun-mode) @(':')@(tsee program) may damage the ACL2
 system in a way that renders it unsound.  In practice, we have never seen this
 happen; so, the explanations below can be viewed as extremely paranoid.
 Nevertheless, here we document this concern, even if it should be taken with
 more than a grain of salt.</p>

 <p>See @(see defun-mode) for a discussion of @(see defun-mode)s.  That
 discussion describes an imagined implementation that is slightly different
 from this one.  This note explains that the current implementation is open to
 unsoundness.</p>

 <p>For discussion of a different soundness issue that is also related to
 function execution, see @(see generalized-booleans).</p>

 <p>The execution of a function having @(see defun-mode) @(':')@(tsee program)
 may violate Common Lisp @(see guard)s on the subroutines used.  (This may be
 true even for calls of a function on arguments that satisfy its @(see guard),
 because ACL2 has not verified that its @(see guard) is sufficient to protect
 its subroutines.)  When a @(see guard) is violated at runtime all bets are
 off.  That is, no guarantees are made either about the answer being ``right''
 or about the continued rationality of the ACL2 system itself.</p>

 <p>For example, suppose you make the following @(tsee defun):</p>

 @({
  (defun crash (i)
    (declare (xargs :mode :program :guard (integerp i)))
    (car i))
 })

 <p>Note that the declared guard does not in fact adequately protect the
 subroutines in the body of @('crash'); indeed, satisfying the guard to
 @('crash') will guarantee that the @(tsee car) expression is in violation of
 its guard.  Because this function is admitted in @(':')@(tsee program)-mode,
 no checks are made concerning the suitability of the guard.  Furthermore, in
 the current ACL2 implementation, @('crash') is executed directly in Common
 Lisp.  Thus if you call @('crash') on an argument satisfying its guard you
 will cause an erroneous computation to take place.</p>

 @({
  ACL2 !>(crash 7)

  Error: Caught fatal error [memory may be damaged]
  ...
 })

 <p>There is no telling how much damage is done by this errant computation.  In
 some lisps your ACL2 job may actually crash back to the operating system.  In
 other lisps you may be able to recover from the ``hard error'' and resume ACL2
 in a damaged but apparently functional image.</p>

 <p>THUS, HAVING A FUNCTION WITH @(see DEFUN-MODE) @(':')@(tsee PROGRAM) IN
 YOUR SYSTEM ABSOLVES US, THE ACL2 IMPLEMENTORS, FROM RESPONSIBILITY FOR THE
 SOUNDNESS OF OUR SYSTEM.</p>

 <p>Furthermore</p>

 <p>ACL2 DOES NOT YET PROVIDE ANY MEANS OF REGAINING ASSURANCES OF SOUNDNESS
 AFTER THE INTRODUCTION OF A FUNCTION IN @(':')@(tsee PROGRAM) MODE, EVEN IF IT
 IS ULTIMATELY CONVERTED TO @(':')@(tsee LOGIC) MODE (since its execution could
 have damaged the system in a way that makes it possible to verify its
 termination and @(see guard)s unsoundly).</p>

 <p>Finally,</p>

 <p>THE VAST MAJORITY OF ACL2 SYSTEM CODE IS IN @(':')@(tsee PROGRAM) MODE AND
 SO ALL BETS ARE OFF FROM BEFORE YOU START!</p>

 <p>This hopeless state of current affairs will change, we think.  We think we
 have defined our functions ``correctly'' in the sense that they can be
 converted, without ``essential'' modification, to @(':')@(tsee logic) mode.
 We think it very unlikely that a mis-guarded function in @(':')@(tsee program)
 mode (whether ours or yours) will cause unsoundness without some sort of hard
 lisp error accompanying it.  We think that ultimately we can make it possible
 to execute your functions (interpretively) without risk to the system, even
 when some have @(':')@(tsee program) mode.  In that imagined implementation,
 code using functions having @(':')@(tsee program) mode would run more slowly,
 but safely.  These functions could be introduced into the logic ex post facto,
 whereupon the code's execution would speed up because Common Lisp would be
 allowed to execute it directly.  We therefore ask that you simply pretend that
 this is that imagined implementation, introduce functions in @(':')@(tsee
 program) mode, use them as convenient and perhaps ultimately introduce some of
 them in @(':')@(tsee logic) mode and prove their properties.  If you use the
 system this way we can develop (or dismiss) this style of formal system
 development.  BUT BE ON THE LOOKOUT FOR SCREWUPS DUE TO DAMAGE CAUSED BY THE
 EXECUTION OF YOUR FUNCTIONS HAVING @(':')@(tsee PROGRAM) MODE!</p>")

(defxdoc defun-mode-lambdas
  :parents (defun-mode)
  :short ":program mode functions in @(tsee LAMBDA) objects"
  :long "<p>A rough rule-of-thumb is that all functions mentioned in a
  @(':')@(tsee logic) mode @(tsee defun) must themselves be in @(':logic')
  mode.  If @('prgm') is a @(':')@(tsee program) mode function then @('(defun
  fn (x) (prgm x))') is illegal.  But there are situations (always involving
  @(tsee apply$)) in which @(':program') mode function symbols are allowed to
  be mentioned in @(':logic') mode @(tsee defun)s.  We explain here.</p>

  <p>Here are two example terms that mention the badged (see @(tsee defbadge))
  @(':program') mode symbol @('prgm').</p>

  @({
  (apply$ (lambda$ (e) (prgm e)) (list x))

  (loop$ for e in lst collect (prgm e))
  })

  <p>Are such terms permitted in the @('defun') of a @(':logic') mode function?
  The answer is complicated because it depends on whether the @('defun') is
  @(tsee loop$) recursive and whether the @('defun') will also try to verify
  the @(tsee guard)s of @('fn').</p>

  <p>First, a @(':logic') mode function may @('apply$') a quoted @(':program')
  mode symbol, whether guards are being verified or not.  For example,
  @('(apply$ 'prgm args)') is legal.  Here @('prgm') is just a quoted symbol.
  Since @('prgm') is a @(':program') mode symbol, there are no axioms about it,
  so during proofs such a call of @('apply$') is not evaluated or expanded.  If
  this form is evaluated at the top-level -- where @(':program') mode functions
  are evaluable -- @('apply$') checks the guards of @('prgm') just as it would
  before any @(':program') mode function is called.</p>

  <p>The situation is more complicated for use of @(':program') mode functions
  in forms like @(tsee lambda$), well-formed quoted @(tsee LAMBDA) objects, and
  @(tsee loop$).  The reason is that in guard-verified code, these forms are
  generally executed via compiled code and that requires that the @('loop$')
  and @('lambda') objects be Common Lisp compliant, which in turn implies they
  must be analyzable by the prover.  Since formally @('loop$')s are understood
  as calls of @(see scion)s on @('lambda$') expressions it suffices for us to
  discuss the @('lambda$') case alone.  Well-formed quoted @('LAMBDA') objects
  are treated the same way.</p>

  <p>So again, suppose you're defining a @(':logic') mode function @('fn').
  Suppose @('fn') is not @('loop$') recursive and guards are not being verified
  during the @('defun').  Then badged @(':program') mode symbols may be used
  @('lambda$') forms in the definition of @('fn').</p>

  <p>If @('fn') is @('loop$') recursive, i.e., @(':')@(tsee loop$-recursion)
  @('t') is declared, then all symbols used as functions in @('lambda$') forms
  must be in @(':logic') mode.  The reason is that the measure conjectures
  generated must be in @(':logic') mode to be provable.</p>

  <p>If @('fn') is to be guard-verified, then all symbols used as functions in
  @('lambda$') forms must be in @(':logic') mode.  The reason is that the guard
  conjectures must be in @(':logic') mode to be provable.</p>

  <p>When a @(':program') function is permitted in a @(':logic') mode definition
  the system will print a warning to alert you to the possibility that proofs
  will fail.  For example, the following events are legal</p>

  @({
  (include-book "projects/apply/top" :dir :system)

  (defun prgm (x)
    (declare (xargs :mode :program))
    (list 'hi x))

  (defbadge prgm)

  (defun fn1 (x)
    (declare (xargs :mode :logic))
    (apply$ 'prgm (list x)))
  })

  <p>but the last event will print:</p>

  @({
  ACL2 Warning [Problematic-quoted-fns] in ( DEFUN FN1 ...): The definition of
  FN1 is in :LOGIC mode but mentions the :PROGRAM mode function HELLO in one or
  more :FN or :EXPR slots.  Conjectures about FN1 may not be provable until
  this program is converted to :LOGIC mode and warranted!  See :DOC
  verify-termination and defwarrant.
  })

  <p>Uses of @('prgm') in quoted well-formed @('LAMBDA') objects, @('lambda$')
  forms, and @('loop$') forms will cause similar warning messages to be
  printed.</p>")

(defxdoc defun-notinline
  :parents (defun events)
  :short "Define a not-to-be-inlined function symbol and associated macro"
  :long "<p>See @(see defun-inline) for an analogous utility that supports
 inlining.  The present utility is probably far less useful; it tells the
 compiler <i>not</i> to inline calls of the function being defined.  Also see
 @(see defund-notinline) for a variant of this event that disables the
 newly-defined function symbol.</p>

 <p>Under the hood, @('(defun-inline f ...)') and @('(defun-notinline f ...)')
 cause evaluation of Common Lisp forms @('(declaim (inline f$inline))') and
 @('(declaim (notinline f$notinline))'), respectively.  According to the Common
 Lisp spec, the compiler need not respect the first of these (for @('inline')),
 but it must respect the second of these (for @('notinline')).  Fortunately,
 Common Lisp implementations often do respect the first of these as well.</p>")

(defxdoc defun-nx
  :parents (defun events)
  :short "Define a non-executable function symbol"
  :long "@({
  Example:

  (defun-nx foo (x state)
    (declare (xargs :guard t))
    (mv-let (a b c)
            (cons x state)
            (list a b c b a)))
  ; Note ``ill-formed'' call of foo just below.
  (defun bar (state y)
    (declare (xargs :stobjs state))
    (foo state y))
 })

 <p>The macro @('defun-nx') introduces definitions using the @(tsee defun)
 macro, always in @(':')@(tsee logic) mode, such that the calls of the
 resulting function cannot be evaluated.  Such a definition is admitted without
 enforcing syntactic restrictions for executability, in particular for
 single-threadedness (see @(see stobj)) and multiple-values passing (see @(see
 mv) and see @(see mv-let)).  After such a definition is admitted, the usual
 syntactic rules for @(tsee state) and user-defined @(see stobj)s are relaxed
 for calls of the function it defines.  Also see @(see non-exec) for a way to
 designate subterms of function bodies, or subterms of code to be executed at
 the top level, as non-executable.</p>

 <p>The syntax of @('defun-nx') is identical to that of @(tsee defun).  A
 form</p>

 @({
  (defun-nx name (x1 ... xk) ... body)
 })

 <p>generates the following definition.</p>

 @({
  (defun name (x1 ... xk)
    (declare (xargs :non-executable t :mode :logic))
    ...
    (prog2$ (throw-nonexec-error 'name (list x1 ... xk))
            body))
 })

 <p>But @('defun-nx') does two other things.  Before executing the @('defun')
 form displayed above, ACL2 arranges that @('state') is allowed as a formal
 parameter, by first introducing @('(set-state-ok t)') in a way that is @(see
 local) to the generated event.  After executing the @('defun'), the @(see
 executable-counterpart) @(see rune) for @('name') is @(see disable)d.  You can
 evaluate @(':trans1 (defun-nx ...)') for your @('defun-nx') form to see its
 single-step macroexpansion.</p>

 <p>Note that because of the insertion of the above call of
 @('throw-nonexec-error'), no formal is ignored when using @('defun-nx').</p>

 <p>During proofs, the error is silent; it is ``caught'' by the proof mechanism
 and generally results in the introduction of a call of @(tsee hide) during a
 proof.  If an error message is produced by evaluating a call of the function
 on a list of arguments that includes @('state') or user-defined @(tsee
 stobj)s, these arguments will be shown as symbols such as @('|<state>|') in
 the error message.  In the case of a user-defined stobj bound by @(tsee
 with-local-stobj) or @(tsee stobj-let), the symbol printed will include the
 suffix @('{instance}'), for example, @('|<st>{instance}|').</p>

 <p>It is harmless to include @(':non-executable t') in your own @(tsee xargs)
 @(tsee declare) form; @('defun-nx') will still lay down its own such
 declaration, but ACL2 can tolerate the duplication.</p>

 <p>Note that @(tsee defund-nx) is also available.  It is essentially identical
 to @('defun-nx') except that as with @(tsee defund), @('defund-nx') leaves the
 definition @(see rune) disabled for the new function symbol.</p>

 <p>If you use guards (see @(see guard)), please be aware that even though
 syntactic restrictions are relaxed for @('defun-nx'), guard verification
 proceeds exactly as for @(tsee defun).  If you want ACL2 to skip a form for
 purposes of generating guard proof obligations, use the macro @(tsee
 non-exec), which generates a call of @('throw-nonexec-error') that differs
 somewhat from the one displayed above.  See @(see non-exec).</p>

 <p>See @(see defun) for documentation of @('defun').</p>")

(defxdoc defun-sk
  :parents (events)
  :short "Define a function whose body has an outermost quantifier"
  :long "@({
  Examples:
  (defun-sk exists-x-p0-and-q0 (y z)
    (exists x
            (and (p0 x y z)
                 (q0 x y z))))

  (defun-sk exists-x-p0-and-q0 (y z) ; equivalent to the above
    (exists (x)
            (and (p0 x y z)
                 (q0 x y z))))

  (defun-sk forall-x-y-p0-and-q0 (z)
    (forall (x y)
            (and (p0 x y z)
                 (q0 x y z)))
    :strengthen t)

  General Form:
  (defun-sk fn (var1 ... varn)
    dcl_1 dcl_2 ... dcl_k
    body
    &key
    rewrite quant-ok skolem-name thm-name strengthen constrain
    verbose)
 })

 <p>where @('fn') is the symbol you wish to define and is a new symbolic @(see
 name), @('(var1 ... varn)') is its list of formal parameters, the optional
 @('dcl_i') forms are @(tsee declare) forms, and @('body') is its body, which
 must be quantified as described below.  The other arguments are explained
 below.</p>

 <p>For a simple example, see @(see defun-sk-example).  For a more elaborate
 example, see @(see Tutorial4-Defun-Sk-Example).  See @(see
 quantifier-tutorial) for a careful beginner's introduction that takes you
 through typical kinds of quantifier-based reasoning in ACL2.  Also see @(see
 quantifiers) for an example illustrating how the use of recursion, rather than
 explicit quantification with @('defun-sk'), may be preferable.</p>

 <p>Below we describe the @('defun-sk') event precisely.  First, let us
 consider the examples above.  The first example, again, is:</p>

 @({
  (defun-sk exists-x-p0-and-q0 (y z)
    (exists x
            (and (p0 x y z)
                 (q0 x y z))))
 })

 <p>It is intended to represent the predicate with formal parameters @('y') and
 @('z') that holds when for some @('x'), @('(and (p0 x y z) (q0 x y z))')
 holds.  In fact @('defun-sk') is a macro, and the call above adds the
 following two @(see events), as shown just below.  The first event guarantees
 that if this new predicate holds of @('y') and @('z'), then the term shown,
 @('(exists-x-p0-and-q0-witness y z)'), is an example of the @('x') that is
 therefore supposed to exist.  (Intuitively, we are axiomatizing
 @('exists-x-p0-and-q0-witness') to pick a witness if there is one.  We comment
 below on the use of @(tsee defun-nx); for now, consider @('defun-nx') to be
 @(tsee defun).)  Conversely, the second event below guarantees that if there
 is any @('x') for which the term in question holds, then the new predicate
 does indeed hold of @('y') and @('z').</p>

 @({
  (defun-nx exists-x-p0-and-q0 (y z)
    (let ((x (exists-x-p0-and-q0-witness y z)))
      (and (p0 x y z) (q0 x y z))))
  (defthm exists-x-p0-and-q0-suff
    (implies (and (p0 x y z) (q0 x y z))
             (exists-x-p0-and-q0 y z)))
 })

 <p>Now let us look at the third example from the introduction above:</p>

 @({
  (defun-sk forall-x-y-p0-and-q0 (z)
    (forall (x y)
            (and (p0 x y z)
                 (q0 x y z))))
 })

 <p>The intention is to introduce a new predicate @('(forall-x-y-p0-and-q0 z)')
 which states that the indicated conjunction holds of all @('x') and all @('y')
 together with the given @('z').  This time, the axioms introduced are as shown
 below.  The first event guarantees that if the application of function
 @('forall-x-y-p0-and-q0-witness') to @('z') picks out values @('x') and @('y')
 for which the given term @('(and (p0 x y z) (q0 x y z))') holds, then the new
 predicate @('forall-x-y-p0-and-q0') holds of @('z').  Conversely, the
 (contrapositive of) the second axiom guarantees that if the new predicate
 holds of @('z'), then the given term holds for all choices of @('x') and
 @('y') (and that same @('z')).</p>

 @({
  (defun-nx forall-x-y-p0-and-q0 (z)
    (mv-let (x y)
            (forall-x-y-p0-and-q0-witness z)
            (and (p0 x y z) (q0 x y z))))
  (defthm forall-x-y-p0-and-q0-necc
    (implies (not (and (p0 x y z) (q0 x y z)))
             (not (forall-x-y-p0-and-q0 z))))
 })

 <p>The examples above suggest the critical property of @('defun-sk'): it
 indeed does introduce the quantified notions that it claims to introduce.</p>

 <p>Notice that the @(tsee defthm) event just above,
 @('forall-x-y-p0-and-q0-necc'), may not be of optimal form as a rewrite rule.
 Users sometimes find that when the quantifier is @('forall'), it is useful to
 state this rule in a form where the new quantified predicate is a hypothesis
 instead.  In this case that form would be as follows:</p>

 @({
  (defthm forall-x-y-p0-and-q0-necc
    (implies (forall-x-y-p0-and-q0 z)
             (and (p0 x y z) (q0 x y z))))
 })

 <p>ACL2 will turn this into one @(':')@(tsee rewrite) rule for each conjunct,
 @('(p0 x y z)') and @('(q0 x y z)'), with hypothesis @('(forall-x-y-p0-and-q0
 z)') in each case.  In order to get this effect, use @(':rewrite :direct'), in
 this case as follows.</p>

 @({
  (defun-sk forall-x-y-p0-and-q0 (z)
    (forall (x y)
            (and (p0 x y z)
                 (q0 x y z)))
    :rewrite :direct)
 })

 <p>We now turn to a detailed description of @('defun-sk'), starting with a
 discussion of its arguments as shown in the "General Form" above.</p>

 <p>The third argument, @('body'), must be of the form</p>

 @({
  (Q bound-vars term)
 })

 <p>where: @('Q') is the symbol @(tsee forall) or @(tsee exists), in the
 "ACL2" package; @('bound-vars') is a variable or true list of variables
 disjoint from @('(var1 ... varn)') and not including @(tsee state); and
 @('term') is a term.  The case that @('bound-vars') is a single variable
 @('v') is treated exactly the same as the case that @('bound-vars') is
 @('(v)').</p>

 <p>The result of this event is to introduce a ``Skolem function,'' whose name
 is the keyword argument @('skolem-name') if that is supplied, and otherwise is
 the result of modifying @('fn') by suffixing "-WITNESS" to its name.  The
 following definition (or a corresponding rule; see the discussion of
 @(':constrain') below) and one of the following two theorems (as indicated)
 are introduced for @('skolem-name') and @('fn') in the case that
 @('bound-vars') (see above) is a single variable @('v').  The name of the
 @(tsee defthm) event may be supplied as the value of the keyword argument
 @(':thm-name'); if it is not supplied, then it is the result of modifying
 @('fn') by suffixing "-SUFF" to its name in the case that the quantifier is
 @(tsee exists), and "-NECC" in the case that the quantifier is @(tsee
 forall).</p>

 @({
  (defun-nx fn (var1 ... varn)
    (let ((v (skolem-name var1 ... varn)))
      term))

  (defthm fn-suff ;in case the quantifier is EXISTS
    (implies term
             (fn var1 ... varn)))

  (defthm fn-necc ;in case the quantifier is FORALL
    (implies (not term)
             (not (fn var1 ... varn))))
 })

 <p>In the @('forall') case, however, the keyword pair @(':rewrite :direct')
 may be supplied after the body of the @('defun-sk') form, in which case the
 contrapositive of the above form is used instead:</p>

 @({
  (defthm fn-necc ;in case the quantifier is FORALL
    (implies (fn var1 ... varn)
             term))
 })

 <p>This is often a better choice for the "-NECC" rule, provided ACL2 can
 parse @('term') as a @(':')@(tsee rewrite) rule.  A second possible value of
 the @(':rewrite') argument of @('defun-sk') is @(':default'), which gives the
 same behavior as when @(':rewrite') is omitted.  Otherwise, the value of
 @(':rewrite') should be the term to use as the body of the @('fn-necc')
 theorem shown above; ACL2 will attempt to do the requisite proof in this case.
 If that term is weaker than the default, the properties introduced by
 @('defun-sk') may of course be weaker than they would be otherwise.  Finally,
 note that the @(':rewrite') keyword argument for @('defun-sk') only makes
 sense if the quantifier is @('forall'); it is thus illegal if the quantifier
 is @('exists').  Enough said about @(':rewrite')!</p>

 <p>In the case that @('bound-vars') is a list of at least two variables, say
 @('(bv1 ... bvk)'), the definition above (with no keywords) is the following
 instead, but the theorem remains unchanged.</p>

 @({
  (defun-nx fn (var1 ... varn)
    (mv-let (bv1 ... bvk)
            (skolem-name var1 ... varn)
            term))
 })

 <p>In order to emphasize that the last element of the list, @('body'), is a
 term, @('defun-sk') checks that the symbols @(tsee forall) and @(tsee exists)
 do not appear anywhere in it.  However, on rare occasions one might
 deliberately choose to violate this convention, presumably because @(tsee
 forall) or @(tsee exists) is being used as a variable or because a macro call
 will be eliminating ``calls of'' @(tsee forall) and @(tsee exists).  In these
 cases, the keyword argument @('quant-ok') may be supplied a non-@('nil')
 value.  Then @('defun-sk') will permit @(tsee forall) and @(tsee exists) in
 the body, but it will still cause an error if there is a real attempt to use
 these symbols as quantifiers.</p>

 <p>The use of @(tsee defun-nx) above, rather than @(tsee defun), disables
 certain checks that are required for evaluation, for example in the passing of
 multiple values.  However, there is a price: calls of these defined functions
 cannot be evaluated; see @(see defun-nx).  Normally that is not a problem,
 since these notions involve quantifiers.  But if you prefer that @(tsee defun)
 be used instead of @('defun-nx'), you can arrange that using @(tsee declare)
 forms, given as the @('dcl_i') as shown above.  These will become the
 @('declare') forms in the generated @(tsee defun).  If the @(tsee xargs) @(see
 declaration) form @(':non-executable nil') is supplied, then @(tsee defun)
 will be used in place of @(tsee defun-nx).</p>

 <p>@(csee Guard) verification is performed for @('defun-sk') events under the
 same conditions as for @('defun') events.  (An exception, ignored here but
 discussed in a later paragraph below, occurs when keyword argument
 @(':constrain t') is supplied.)  Thus, by default, guard verification will be
 attempted exactly when at least one of @('type'), @(':guard'), or
 @(':verify-guards t') is specified in a declaration (that is, in some
 @('dcl_i').  This default behavior can be modified just as it is for
 @('defun'); see @(tsee set-verify-guards-eagerness).  Technical note: such
 guard verification is implemented through a generated call of @(tsee
 verify-guards) after the @('encapsulate') that surrounds the definitions
 introduced; use @(':')@(tsee trans1) to see the expansion.</p>

 <p>@('Defun-sk') is a macro implemented using @(tsee defchoose).  Hence, it
 should only be executed in @(see defun-mode) @(':')@(tsee logic); see @(see
 defun-mode) and see @(see defchoose).  You can use the command @(':')@(tsee
 pcb!) to see the event generated by a call of the @('defun-sk') macro.  If you
 want to watch the subsidiary events (including the @('defchoose') event) as
 they are being executed, use keyword option @(':verbose t').</p>

 <p>An advanced feature is argument @(':strengthen t'), which generates the
 extra constraint that is generated for the corresponding @('defchoose') event;
 see @(see defchoose).  The name of that generated theorem will be obtained by
 adding the suffix @('"-STRENGTHEN"') to the function symbol being defined,
 in the same package.</p>

 <p>If you find that the rewrite rules introduced with a particular use of
 @('defun-sk') are not ideal, even when using the @(':rewrite') keyword
 discussed above (in the @('forall') case), then at least two reasonable
 courses of action are available for you.  Perhaps the best option is to prove
 the @(tsee rewrite) rules you want.  If you see a pattern for creating rewrite
 rules from your @('defun-sk') events, you might want to write a macro that
 executes a @('defun-sk') followed by one or more @(tsee defthm) events.
 Another option is to write your own variant of the @('defun-sk') macro, say,
 @('my-defun-sk'), for example by modifying a copy of the definition of
 @('defun-sk') from the ACL2 sources.</p>

 <p>There is one more keyword argument not explained above: @(':constrain').
 The default is @('nil'); otherwise this argument must be a symbol, which we
 call @('name-def'), except that in the case of @('t'), @('name-def') is
 obtained by adding the suffix @('"-DEFINITION"') to @('fn').  For a
 non-@('nil') @(':constrain') argument, this @('name-def') is the name of a
 rule of class @(':')@(tsee definition) that equates @('(fn var1 ... varn)')
 with the body of the definition of @('fn').  Furthermore, in this case of a
 non-@('nil') @(':constrain') value the definition of @('fn') is local to the
 surrounding @('encapsulate'), which contains a signature for @('fn').  As
 usual, the simplest way to see the effects of @(':constrain') may be to apply
 @(':trans1') to your @('defun-sk') form.  Note that constraining the function
 can make it possible to attach to it (see @(see defattach)) and to introduce
 it as a @(see guard)-verified function.  Also note that when @(':constrain t')
 is specified: the guard of @('fn') will automatically be @('t'), no guard
 verification will be performed, and @('fn') will nevertheless be a
 guard-verified (and constrained) function.</p>

 <p>If you want to represent nested quantifiers, you can use more than one
 @('defun-sk') event.  For example, in order to represent</p>

 @({
  (forall x (exists y (p x y z)))
 })

 <p>you can use @('defun-sk') twice, for example as follows.</p>

 @({
  (defun-sk exists-y-p (x z)
    (exists y (p x y z)))

  (defun-sk forall-x-exists-y-p (z)
    (forall x (exists-y-p x z)))
 })

 <p>Some distracting and unimportant warnings are inhibited during
 @('defun-sk').</p>

 <p>Note for ACL2(r) users (see @(see real)): In ACL2(r), the keyword
 @(':CLASSICALP') is also supported.  Its legal values are @('t') (the default)
 and @('nil'), and it determines whether or not (respectively) ACL2(r) will
 consider @('fn') to be a classical function.  It must be the case that the
 value is @('t') (perhaps implicitly, by default) if and only if @('body') is
 classical.</p>

 <p>Note that this way of implementing quantifiers is not a new idea.  Hilbert
 was certainly aware of it in the first half of the 20th century!  Also see
 @(see conservativity-of-defchoose) for a technical argument that justifies the
 logical conservativity of the @(tsee defchoose) event in the sense of the
 paper by Kaufmann and Moore entitled ``Structured Theory Development for a
 Mechanized Logic'' (Journal of Automated Reasoning 26, no. 2 (2001),
 pp. 161&ndash;203).</p>")

(defxdoc defun-sk-example
  :parents (defun-sk)
  :short "A simple example using @(tsee defun-sk)"
  :long "<p>For a more thorough, systematic beginner's introduction to
 quantification in ACL2, see @(see quantifier-tutorial).</p>

 <p>The following example illustrates how to do proofs about functions defined
 with @(tsee defun-sk).  The events below can be put into a certifiable book
 (see @(see books)).  The example is contrived and rather silly, in that it
 shows how to prove that a quantified notion implies itself, where the
 antecedent and conclusion are defined with different @(tsee defun-sk) events.
 But it illustrates the formulas that are generated by @(tsee defun-sk), and
 how to use them.  Thanks to Julien Schmaltz for presenting this example as a
 challenge.</p>

 @({
  (in-package "ACL2")

  (encapsulate
   (((p *) => *)
    ((expr *) => *))

   (local (defun p (x) x))
   (local (defun expr (x) x)))

  (defun-sk forall-expr1 (x)
    (forall (y) (implies (p x) (expr y))))

  (defun-sk forall-expr2 (x)
    (forall (y) (implies (p x) (expr y)))))

  ; We want to prove the theorem my-theorem below.  What axioms are there that
  ; can help us?  If you submit the command

  ; :pcb! forall-expr1

  ; then you will see the following two key events.  (They are completely
  ; analogous of course for FORALL-EXPR2.)

  ;   (DEFUN FORALL-EXPR1 (X)
  ;     (LET ((Y (FORALL-EXPR1-WITNESS X)))
  ;          (IMPLIES (P X) (EXPR Y))))
  ;
  ;   (DEFTHM FORALL-EXPR1-NECC
  ;     (IMPLIES (NOT (IMPLIES (P X) (EXPR Y)))
  ;              (NOT (FORALL-EXPR1 X)))
  ;     :HINTS
  ;     (("Goal" :USE FORALL-EXPR1-WITNESS)))

  ; We see that the latter has value when FORALL-EXPR1 occurs negated in a
  ; conclusion, or (therefore) positively in a hypothesis.  A good rule to
  ; remember is that the former has value in the opposite circumstance: negated
  ; in a hypothesis or positively in a conclusion.

  ; In our theorem, FORALL-EXPR2 occurs positively in the conclusion, so its
  ; definition should be of use.  We therefore leave its definition enabled,
  ; and disable the definition of FORALL-EXPR1.

  ;   (thm
  ;     (implies (and (p x) (forall-expr1 x))
  ;              (forall-expr2 x))
  ;     :hints (("Goal" :in-theory (disable forall-expr1))))
  ;
  ;   ; which yields this unproved subgoal:
  ;
  ;   (IMPLIES (AND (P X) (FORALL-EXPR1 X))
  ;            (EXPR (FORALL-EXPR2-WITNESS X)))

  ; Now we can see how to use FORALL-EXPR1-NECC to complete the proof, by
  ; binding y to (FORALL-EXPR2-WITNESS X).

  ; We use defthmd below so that the following doesn't interfere with the
  ; second proof, in my-theorem-again that follows.
  (defthmd my-theorem
    (implies (and (p x) (forall-expr1 x))
             (forall-expr2 x))
    :hints (("Goal"
             :use ((:instance forall-expr1-necc
                              (x x)
                              (y (forall-expr2-witness x)))))))

  ; The following illustrates a more advanced technique to consider in such
  ; cases.  If we disable forall-expr1, then we can similarly succeed by having
  ; FORALL-EXPR1-NECC applied as a :rewrite rule, with an appropriate hint in how
  ; to instantiate its free variable.  See :doc hints.

  (defthm my-theorem-again
    (implies (and (P x) (forall-expr1 x))
             (forall-expr2 x))
    :hints (("Goal"
             :in-theory (disable forall-expr1)
             :restrict ((forall-expr1-necc
                         ((y (forall-expr2-witness x))))))))
 })")

(defxdoc defund
  :parents (defun events)
  :short "Define a function symbol and then disable it"
  :long "<p>Use @('defund') instead of @(tsee defun) when you want to @(see
 disable) a function immediately after its definition in @(':')@(tsee logic)
 mode.  This macro has been provided for users who prefer working in a mode
 where functions are only enabled when explicitly directed by @(':')@(tsee
 in-theory).  Specifically, the form</p>

 @({
  (defund NAME FORMALS ...)
 })

 <p>expands to the following, except that some output is inhibited for the
 @(tsee in-theory) event:</p>

 @({
  (progn
    (defun NAME FORMALS ...)
    (in-theory (disable NAME))
    (value-triple '(:defund NAME))).
 })

 <p>Only the @(':')@(tsee definition) rule and, for recursively defined
 functions, the @(':')@(tsee induction) rule are disabled for the function.
 In particular, @('defund') does not disable either the @(':')@(tsee
 type-prescription) or the @(':')@(tsee executable-counterpart) rule.</p>

 <p>If the function is defined in @(':')@(tsee program) mode, either because
 the @(see default-defun-mode) is @(':')@(tsee program) or because @(':mode
 :program') has been specified in an @(tsee xargs) form of a @(tsee declare)
 form, then no @(tsee in-theory) event is executed.  (More precisely, @(tsee
 in-theory) events are ignored when the @(see default-defun-mode) is
 @(':')@(tsee program), and if @(':mode :program') is specified then
 @('defund') does not generate an @(tsee in-theory) event.)</p>

 <p>@('Defund') events are generally not redundant, because the generated
 @(tsee in-theory) event is not redundant.  This default can be changed; see
 @(see set-in-theory-redundant-okp).</p>

 <p>See @(see defun) for documentation of @('defun').</p>")

(defxdoc defund-inline
  :parents (defun events)
  :short "Define a potentially disabled, inlined function symbol and associated macro"
  :long "<p>@('Defund-inline') is a variant of @(tsee defun-inline), the
 difference being that @('defund-inline') disables the newly-defined function
 symbol.  See @(see defun-inline).</p>")

(defxdoc defund-notinline
  :parents (defun events)
  :short "Define a disabled, not-to-be-inlined function symbol and associated macro"
  :long "<p>@('Defund-notinline') is a variant of @(tsee defun-notinline), the
 difference being that @('defund-notinline') disables the newly-defined
 function symbol.  See @(see defun-notinline).</p>")

(defxdoc defund-nx
  :parents (defun events)
  :short "Define a disabled non-executable function symbol"
  :long "<p>Use @('defund-nx') instead of @(tsee defun-nx) when you want to
 @(see disable) the definition of a function symbol immediately after defining
 it in @(':')@(tsee logic) mode.  In all other respects, @('defund-nx') has the
 same behavior as @('defun-nx'); See @(see defun-nx) for details.  Also see
 @(see defund).</p>")

(defxdoc defuns
  :parents (mutual-recursion)
  :short "An alternative to @(tsee mutual-recursion)"
  :long "@({
  Example:
  (DEFUNS
   (evenlp (x)
     (if (consp x) (oddlp (cdr x)) t))
   (oddlp (x)
     (if (consp x) (evenlp (cdr x)) nil)))

  General Form:
  (DEFUNS defuns-tuple1 ... defuns-tuplen)
 })

 <p>is equivalent to</p>

 @({
  (MUTUAL-RECURSION
    (DEFUN . defuns-tuple1)
    ...
    (DEFUN . defuns-tuplen))
 })

 <p>In fact, @('defuns') is the more primitive of the two and @(tsee
 mutual-recursion) is just a macro that expands to a call of @('defuns')
 after stripping off the @(tsee defun) at the @(tsee car) of each argument to
 @(tsee mutual-recursion).  We provide and use @(tsee mutual-recursion) rather
 than @('defuns') because by leaving the @(tsee defun)s in place, @(tsee
 mutual-recursion) forms can be processed by the Emacs @('tags') program.  See
 @(see mutual-recursion).</p>")

(defxdoc defwarrant
  :parents (apply$ acl2-built-ins)
  :short "Issue a warrant for a function so @(tsee apply$) can use it in proofs"
  :long "<p>It is best to be somewhat familiar with the documentation of @(tsee
  apply$) before reading this topic.</p>

  <p>Before using @('defwarrant') or a utility like @(tsee defun$) that relies
  on it:</p>

  @({
  (include-book "projects/apply/top" :dir :system)
  })

  <p>Several lemmas in that book are necessary for @('defwarrant') to prove
  the theorems it must prove.</p>

  <h3>Badges versus Warrants</h3>

  <p>It is easy to confuse @(see badge)s, which are issued by @(tsee defbadge),
  with @(see warrant)s, which are issued by @('defwarrant').  See the first
  section of @(tsee defbadge) for an extended discussion.</p>

  <h3>Requirements of @('Defwarrant')</h3>

  @({
  General Form:
  (defwarrant fn)
  })

  <p>where @('fn') is a defined function name.  This command analyzes the body
  of @('fn') to determine whether it satisfies certain stringent syntactic and
  semantic conditions that allow the ACL2 proof theory to be extended so that
  the prover can simplify forms like @('(apply$ 'fn ...)').  The syntactic
  conditions include those of @(tsee defbadge), which @('defwarrant')
  essentially invokes if @('fn') is a @(':')@(tsee logic) mode function that is
  not already badged.  But below we describe all the conditions checked by
  @('defwarrant') since many users use @('defwarrant') to issue both a badge
  and a warrant.</p>

  <p>Basic conditions include that @('fn') is in @(':')@(tsee logic)-mode and
  that its justification (i.e., the measure, well-founded relation, and domain
  predicate used to admit @('fn')) be expressible without any reference to
  @(tsee apply$), @(tsee ev$), or @(tsee apply$-userfn).</p>

  <p>@('Defwarrant') imposes some additional conditions on @('fn'), but exactly
  what those conditions are depends on a certain ``reachability'' test detailed
  in the section titled <b>The ``Reachability'' Test</b> in @(tsee defbadge).
  Roughly speaking the test is whether @('apply$') is ancestral in @('fn'),
  meaning @('apply$') is somehow involved in the definition of @('fn') or the
  functions it calls.</p>

  <p>If the reachability test succeeds &mdash; colloquially, if @('fn') depends
  on @('apply$') &mdash; then @('defwarrant') imposes the following additional
  conditions in order to issue a warrant.</p>

  <p><i>(a)</i> If @('fn') is recursive it must not be part of a mutually
  recursive clique and its measure must be of type @(tsee NATP) or be a
  lexicographic combination of natural numbers as defined by the @('llist')
  function in the Community Books at @('books/ordinals/').</p>

  <p><i>(b)</i> Every function called in the body of @('fn'), except @('fn')
  itself, must already have a @(see badge) and a warrant.  If some subfunction
  doesn't already have a badge, @('defwarrant') will call @(tsee defbadge) and
  signal an error if that fails.  If some subfunction doesn't already have a
  warrant, @('defwarrant') will signal an error and suggest that you call
  @('defwarrant') on the offending subfunction first.  @('Defwarrant') will
  continue to fail until all subfunctions have badges and warrants.</p>

  <p><i>(c)</i> It must be possible for each formal of @('fn') to be assigned
  one of three @(see ilk)s, @(':FN'), @(':EXPR'), or @('NIL'), as described
  below.  The basic idea is that a formal can be assigned ilk @(':FN') (or ilk
  @(':EXPR')) iff it is sometimes passed into a @(':FN') (or @(':EXPR')) slot
  in the body of @('fn') and is never passed into any other kind of slot.  A
  formal can be be assigned ilk @('NIL') iff it is never passed into a slot of
  ilk @(':FN') or @(':EXPR'), i.e., if it is used as an ``ordinary'' object.
  We are more precise below.</p>

  <p><i>(d)</i> Every @(':FN') and @(':EXPR') slot of every function called in
  the body of @('fn') is occupied either by a formal of @('fn') of the same ilk
  or, in the case of calls of functions other than @('fn'), a quoted @(see
  tame) function symbol or quoted tame (preferably well-formed) @('LAMBDA')
  object.</p>

  <p>This completes the list of additional restrictions imposed by
  @('defwarrant') on @('fn'), when @('apply$') is reachable from @('fn').</p>

  <p>If the reachability test fails &mdash; colloquially, if @('fn') does not
  depend on @('apply$') &mdash; then @('defwarrant') just checks that @('fn')
  does not call any of a few functions that @('apply$') is prohibited from
  running.  Among those blacklisted functions are @(tsee sys-call) and other
  functions requiring a trust tag.  For a list of the blacklisted functions see
  the value of @('*blacklisted-apply$-fns*').</p>

  <p>Note that the restrictions imposed on functions from which @('apply$')
  cannot be reached are comparatively generous.  If @('fn') does not depend on
  @('apply$') then @('fn') can be warranted despite (a) being defined mutually
  recursively or with an arbitrary ordinal measure, or (b) calling unbadged or
  unbadgeable functions.  @('Defwarrant') can be relaxed in this case because
  the warrant constrains @('(apply$ 'fn ...)') to be @('(fn ...)') and @('fn')
  is a well-defined @(':logic') mode function that is independent of
  @('apply$').  Thus, in the model of @('apply$') that justifies the whole
  @('apply$') story, the handling of @('fn') is just a base case.  The
  situation would be more restrictive if the warrant constrained @('(apply$ 'fn
  ...)') to evaluate the body of @('fn') with @(tsee ev$) which would possibly
  raise termination issues.</p>

  <p>Regardless of whether @('apply$') is reachable, if the requisite
  conditions are not met, @('defwarrant') causes an error.</p>

  <p>If the requisite conditions are met, @('defwarrant') obtains or constructs
  the @(see badge) for @('fn'), setting the arity and out arity appropriately
  and setting the ilks field to the list of computed ilks (or to @('T') if
  every formal has ilk @('NIL')).  The generated badge is stored for the future
  use of @('defwarrant').  See @(tsee defbadge) for a brief discussion of how
  ilks are computed.</p>

  <p>Furthermore, @('defwarrant') generates the @(tsee warrant) for @('fn').
  The name of that 0-ary function will be @('APPLY$-WARRANT-fn').  Calls of
  @(tsee apply$) on @(''fn') in proof attempts can only be simplified if the
  warrant hypothesis, @('(APPLY$-WARRANT-fn)'), <i>aka</i> ``the warrant,'' is
  among the hypotheses of the conjecture being proved.  The warrant specifies
  the values of both @('(badge 'fn)') and @('(apply$ 'fn ...)'), including the
  tameness requirements imposed on @('apply$').  (The warrant explicitly
  specifies the values of @(tsee badge-userfn) and @(tsee apply$-userfn) and
  then @(tsee defwarrant) proves rewrite rules to make calls of @('badge') and
  @('apply$') simplify accordingly.)</p>

  <p>If a warrant is issued for @('fn'), then @('defwarrant') also extends
  ACL2's evaluation theory (but not its proof theory) so that the warrant
  hypothesis is assumed true in that theory, allowing calls of @('badge') and
  @('apply$') to be evaluated in the evaluation theory (but not in the proof
  theory).  See @(tsee warrant) for details.</p>

  <p>You might worry that theorems burdened by warrants are vacuously valid
  because it might be impossible to satisfy all the warrant hypotheses.  You
  needn't worry about this.  <i>There is a model of @('apply$') and all of its
  @(tsee scion)s that makes every warrant issued by @('defwarrant') valid.</i>
  The proof of this is sketched in <a
  href='http://www.cs.utexas.edu/users/kaufmann/papers/apply/index.html'>``Limited
  Second-Order Functionality in a First-Order Setting''</a> by Matt Kaufmann
  and J Strother Moore and fully fleshed out in the comment titled <tt>Essay on
  Admitting a Model for Apply$ and the Functions that Use It</tt> in the ACL2
  source file @('apply-raw.lisp').</p>

  <p>@('Defwarrant') also proves that @(tsee fn-equal) is a congruence
  relation for each @(':FN') position of @('fn').</p>")

(defxdoc delete-assoc
  :parents (alists acl2-built-ins)
  :short "Deprecated version of @(see remove1-assoc)"
  :long "<p>See @(see remove1-assoc).</p>")

(defxdoc delete-file$
  :parents (io)
  :short "Delete a file"
  :long "<p>This analogue of the Common Lisp function, @('delete-file'), uses
 that function under the hood to delete a given file.  It returns @('(mv t
 state)') if deletion succeeds and @('(mv nil state)') otherwise.  The @(tsee
 guard) of @('delete-file$') requires that the first argument is a string; the
 second argument is the ACL2 @(tsee state).  The logical definition does not
 actually look at the file and hence is not useful for reasoning.</p>

 @(def delete-file$)")

(defxdoc delete-include-book-dir
  :parents (books-reference)
  :short "Unlink keyword for @(':dir') argument of @(tsee ld) and @(tsee
include-book)"
  :long "@({
 Example Forms:
 ; Remove association of a directory with :smith for include-book and ld:
 (delete-include-book-dir :smith)

 General Form:
 (delete-include-book-dir kwd)
 })

 <p>where @('kwd') is a @(tsee keywordp).  The effect of this event is to
 modify the meaning of the @(':dir') keyword argument of @(tsee include-book)
 and @(tsee ld) as indicated by the example above, namely by removing
 association of a directory with the indicated keyword for purposes of the
 @(':dir') argument of @(tsee include-book) and @(tsee ld).  See @(tsee
 add-include-book-dir) for how to associate a new directory with a keyword.</p>

 <p>Note: This is an event!  It does not print the usual event @(see summary)
 but nevertheless changes the ACL2 logical @(see world) and is so recorded.</p>

 <p>This macro is @(tsee local) to any @(see books) and @(tsee encapsulate)
 @(see events) in which it occurs; see @(see add-include-book-dir) for a
 discussion of this aspect of both macros.  For non-local associations of
 keywords with directories, see @(see add-include-book-dir!) and @(see
 delete-include-book-dir!).  Note that @('delete-include-book-dir') may only be
 used to remove keywords added by calls of @(tsee add-include-book-dir), and
 @(tsee delete-include-book-dir!) may only be used to remove keywords added by
 calls of @(tsee add-include-book-dir!)</p>")

(defxdoc delete-include-book-dir!
  :parents (books-reference)
  :short "Non-@(tsee local)ly unlink keyword for @(':dir') argument of @(tsee
ld) and @(tsee include-book)"
  :long "<p>Please see @(see delete-include-book-dir), which has completely
 analogous syntax and semantics, but is used for removing associations
 previously placed by @(tsee add-include-book-dir).  By contrast,
 @('delete-include-book-dir!') removes associations previously placed by
 @(tsee add-include-book-dir!).</p>

 <p>Note: This is an event!  It does not print the usual event @(see summary)
 but nevertheless changes the ACL2 logical @(see world) and is so recorded.</p>

 <p>This macro is essentially a @(tsee table) event that updates the table
 @('include-book-dir!-table'), which associates keywords with absolute
 pathnames.  However, as with @(tsee delete-include-book-dir), direct table
 updates are disallowed; you must use @('delete-include-book-dir!') to remove
 from the table and @(tsee add-include-book-dir!) to add to the table.</p>

 <p>It is illegal to call @('delete-include-book-dir!') in a @(tsee local)
 context.  For an explanation, see @(see add-include-book-dir!).</p>")

(defxdoc denominator
  :parents (numbers acl2-built-ins)
  :short "Divisor of a ratio in lowest terms"
  :long "<p>Completion Axiom (@('completion-of-denominator')):</p>

 @({
  (equal (denominator x)
         (if (rationalp x)
             (denominator x)
           1))
 })

 <p>@(see Guard) for @('(denominator x)'):</p>

 @({
  (rationalp x)
 })")

(defxdoc df
  :parents (numbers acl2-built-ins)
  :short "Support for floating-point operations"
  :long "<p>ACL2 supports computation that uses floating-point operations.  The
 basic arithmetic operations (@('+'), @('-'), @('*'), and @('/')) in Common
 Lisp can be much faster when applied to floating-point numbers than to
 rational numbers.  Moreover, the floating-point operations include
 transcendental operations such as the sine function.</p>

 <p>All floating-point computations performed by Common Lisp for ACL2 use
 <i>double-floats</i>, that is, double-precision floating-point numbers.
 Computation with other precisions (including single-precision) is not
 supported by ACL2.</p>

 <p>Note: ACL2 novices are advised to skip this topic and program with ordinary
 ACL2 rationals rather than taking advantage of ACL2 support for floating-point
 operations.  The syntactic restrictions described below are somewhat like
 those for single-threaded objects, known as @(see stobj)s, so although
 familiarity with stobjs is not assumed, that familiarity may be helpful for
 understanding ACL2 support for floating-point computations.  (But for
 expressions denoting floating-point computations, unlike those involving
 stobjs, there is no restriction to single instances and there are no
 destructive operations.)</p>

 <p>This topic is organized as follows.  The Introduction may suffice for those
 eager to start playing with ACL2's version of floating-point operations.  The
 second section presents challenges for supporting floating-point operations in
 ACL2, and the third section outlines how ACL2 addresses those challenges.  A
 key enabler for ACL2 support of floating-point operations is how it restricts
 their use syntactically, and this is discussed in Section 4.  Section 5
 discusses guards.  Section 6 documents the built-in ACL2 functions and macros
 that involve floating-point operations.  Section 7 makes some remarks on
 performance.  Finally, Section 8 covers more aspects of ACL2 support for
 floating-point operations by presenting highlights of a substantial file of
 relevant examples: the @(see community-book),
 @('books/demos/floating-point-input.lsp').  We conclude in Section 9 with
 remarks for system programmers.</p>

 <p>This topic is written for ACL2 users.  Implementation-level remarks for
 developers may be found in a comment in the ACL2 sources entitled &ldquo;Essay
 on Support for Floating-point (double-float, df) Operations in
 ACL2&rdquo;.</p>

 <h3>Section 1: Introduction</h3>

 <p>ACL2 differs from Common Lisp by imposing syntactic restrictions on
 expressions that represent floating-point computations, to ensure that these
 computations respect the ACL2 axioms.  Those expressions are called <i>df
 expressions</i>, or <i>dfs</i> for short.  ACL2 may also say that such an
 expression &ldquo;returns a result of shape :DF&rdquo;.</p>

 <p>With those restrictions, ACL2 supports computations with double-precision
 floating-point numbers without adding a floating-point data type to the logic.
 Rather, ACL2 logically treats df expressions as returning rational numbers
 that are <i>representable</i> by floating-point numbers.  For example, there
 is no floating-point number 1.5 in the ACL2 logic; rather, the Common Lisp
 value 1.5 represents the rational number 3/2, which is an ACL2 object, and the
 df expression @('(to-df 3/2)') is provably equal to the constant 3/2 in the
 logic, even though evaluation of @('(to-df 3/2)') in Common Lisp returns the
 double-float 1.5.  Discussion below further explains dfs in ACL2, but for
 starters let's consider the following example.</p>

 @({
 (defun f1 (x)
   (declare (type double-float x))
   (df- x))
 })

 <p>ACL2 admits this definition so that @('f1') is a @(see guard)-verified
 function.  The operation @('df-') is essentially just the negative operation
 (@('-')), except that @('df-') is to be applied only to df expressions; this
 is enforced based on the @('double-float') type declaration.  Let's look at
 what happens when we @(see trace) @('f1'); discussion follows.  In the
 following example, @('f1') is applied to the df expression @('(to-df 3/2)');
 the expression @('(f1 3/2)') would be illegal for top-level evaluation
 because, as noted above, @('f1') expects a df expression, </p>

 @({
 ACL2 !>(trace$ f1 to-df)
 ((F1) (TO-DF))
 ACL2 !>(f1 (to-df 3/2))
 1> (ACL2_*1*_ACL2::TO-DF 3/2)
 <1 (ACL2_*1*_ACL2::TO-DF 3/2)
 1> (ACL2_*1*_ACL2::F1 3/2)
   2> (F1 1.5)
   <2 (F1 -1.5)
 <1 (ACL2_*1*_ACL2::F1 -3/2)
 #d-1.5
 ACL2 !>
 })

 <p>Initially, the function @('to-df') is applied to 3/2.  The result is
 logically still 3/2, not 1.5, because the <i>executable-counterpart</i> for
 @('to-df') returns an ACL2 value, not a Common Lisp value.  (See @(see
 evaluation) for background on executable-counterparts and corresponding raw
 Lisp functions.)  Then 3/2 is passed to the executable-counterpart for
 @('f1').  The @(see guard) of @('f1') holds on 3/2 (we'll discuss guards
 later), so evaluation passes from the executable-counterpart for @('f1') to
 the raw Lisp function for @('f1') after converting 3/2 to a Common Lisp
 double-precision floating-point number, 1.5.  Then @('df-'), which is
 essentially just @('-') in raw Lisp, is applied to obtain -1.5, which is
 returned by raw-Lisp @('f1').  Then the executable-counterpart for @('f1')
 converts -1.5 to the corresponding ACL2 object, the rational -3/2, which is
 ultimately returned to the top-level loop.</p>

 <p>Remark.  The astute reader may have noticed that the executable-counterpart
 for @('to-df') did not call the raw Lisp function for @('to-df').  That is
 because @('to-df') is actually a macro in raw Lisp.</p>

 <h3>Section 2: Challenges for supporting floating-point operations in
 ACL2</h3>

 <p>In this section we motivate ACL2 restrictions pertaining to floating-point
 numbers, which are addressed in the section after this one.</p>

 <p>We start with examples that show why ACL2 cannot allow some common
 operations to be applied to floating-point numbers.  We illustrate using
 computations in raw Lisp; this is relevant since, as noted above, raw-Lisp
 computation supports @(see evaluation) of @(see guard)-verified code.</p>

 <p><b>Problem #1</b>: Addition isn't associative on floating-point
 numbers.</p>

 <p>We see that immediately with the following raw Lisp examples.</p>

 @({
 ? (+ 0.1 (+ 0.2 0.3))
 0.6
 ? (+ (+ 0.1 0.2) 0.3)
 0.6000000000000001
 ?
 })

 <p>Yet ACL2 has the following axiom.</p>

 @(def associativity-of-+)

 <p>So we can't simply apply @('+') to floating-point numbers in ACL2, because
 @(see guard)-verified code leads to raw Lisp computations that would violate
 this axiom.</p>

 <p><b>Problem #2</b>: Functions @('EQUAL') and @('=') are logically the same
 in ACL2 but not in raw Lisp.</p>

 <p>The following succeeds.</p>

 @({
 (thm (equal (equal x y)
             (= x y)))
 })

 <p>Yet the following log shows that raw Lisp can violate that property if we
 allow double-floats.  (In Common Lisp, @('=') compares numeric values while
 @('EQUAL') distinguishes between rationals and floats and even between
 floating-point numbers 0.0 and -0.0.)</p>

 @({
 ? (equal 1 1.0)
 NIL
 ? (= 1 1.0)
 T
 ? (equal 0.0 (- 0.0))
 NIL
 ? (= 0.0 (- 0.0))
 T
 ?
 })

 <h3>Section 3: How the challenges are addressed</h3>

 <p>The following three principles guide support for floating-point
 computations in ACL2.</p>

 <ul>

 <li>(A) Treat floating-point values as rationals.</li>

 <li>(B) Put syntactic limitations on floating-point operations.</li>

 <li>(C) Use @(see partial-encapsulate) to axiomatize floating-point operations
 while supporting evaluation.</li>

 </ul>

 <p>Let's look at these in turn.</p>

 <p><b>(A) Treat floating-point values as rationals.</b></p>

 <p>The ACL2 logic does not include floating-point numbers.  Rather, certain
 rational numbers can be <i>represented by</i> double-precision floating-point
 numbers, known as double-floats, during computations.  We can say that a
 double-float <i>represents</i> a corresponding rational number.  Certain
 expressions denote such <i>representable</i> rational numbers.  Those are
 called <i>df expressions</i> and we say more about them in our discussion of
 (B), below.</p>

 <p>The predicate @('dfp') recognizes those rational numbers that have a
 floating-point representation.  We do not review floating-point numbers here,
 other than to note that a floating-point number is equal to a binary
 significand between 1 and 2 times 2 to a power, such as as @('1.01100 *
 2^30').  For example, 1/4 is representable but 1/3 is not.</p>

 @({
 ACL2 !>(dfp 1/4) ; represented by the double-float, 0.25d0
 T
 ACL2 !>(dfp 1/3) ; not represented by a double-float
 NIL
 ACL2 !>
 })

 <p>ACL2 provides @('#d') notation (see @(see sharp-d-reader)) as a way to read
 floating-point notation as a representable rational, illustrated as
 follows.</p>

 @({
 ACL2 !>#d0.25
 1/4
 ACL2 !>#d3.5
 7/2
 ACL2 !>#d3.1
 6980579422424269/2251799813685248
 ACL2 !>:q

 Exiting the ACL2 read-eval-print loop.  To re-enter, execute (LP).
 ? (= 3.1 6980579422424269/2251799813685248)
 T
 ?
 })

 <p>Although ACL2 simulates floating-point values with rationals, we see below
 how raw Lisp computation can actually use floating-point arithmetic on
 double-precision floating-point numbers.</p>

 <p><b>(B) Put syntactic limitations on floating-point operations.</b></p>

 <p>Here we briefly discuss syntactic restrictions based on the notion
 mentioned above of <i>df expression</i>, or <i>df</i> for short.  A more
 complete discussion is in the section below on Syntactic Restrictions.  With
 those restrictions, ACL2 supports computations with double-precision
 floating-point numbers without adding a floating-point data type to the logic.
 Informally, a df expression is one that computes in raw Lisp to a
 double-float.</p>

 <p>Let us return to the following example.  It uses @('df-'), which is the
 negative operation on dfs; that is, @('(df- x)') is analogous to @('(- x)'),
 but @('df-') operates on a df and returns a df.</p>

 @({
 ACL2 !>(defun f1 (x)
          (declare (type double-float x))
          (df- x))

 Since F1 is non-recursive, its admission is trivial.  We observe that
 the type of F1 is described by the theorem (RATIONALP (F1 X)).  We
 used the :type-prescription rule BINARY-DF+.

 (F1 :DF) => :DF.

 Computing the guard conjecture for F1....

 The guard conjecture for F1 is trivial to prove.  F1 is compliant with
 Common Lisp.

 Summary
 Form:  ( DEFUN F1 ...)
 Rules: ((:TYPE-PRESCRIPTION BINARY-DF+))
 Time:  0.01 seconds (prove: 0.00, print: 0.00, other: 0.01)
  F1
 ACL2 !>
 })

 <p>Notice the signature shown above for @('f1'):</p>

 @({
 (F1 :DF) => :DF
 })

 <p>This means that the input of @('f1') must be a df expression and @('f1')
 returns a df expression.  ACL2 determines that the input must be a df by
 virtue of the declaration, @('(type double-float x)').  Calls of @('f1') are
 determined to be dfs because the body of @('f1'), @('(df- x)'), is a df.  One
 can say that ACL2 engages in a limited form of strong typing to identify
 certain inputs and outputs of a function symbol as dfs.  Those familiar with
 @(see stobj)s may notice some similarity to the syntactic restrictions on
 stobjs.</p>

 <p>The following example illustrates the requirement that the input of @('f1')
 be a df.</p>

 @({
 ACL2 !>(f1 3)


 ACL2 Error [Translate] in TOP-LEVEL:  The form 3 represents an ordinary
 object, but it is being used where a form representing a :DF was expected.
 See :DOC df.  Note:  this error occurred in the context (F1 3).

 ACL2 !>
 })

 <p>That error can be avoided by converting the input (a rational constant) to
 a suitable df using the primitive, @('to-df') (discussed later).</p>

 @({
 ACL2 !>(f1 (to-df 3))
 #d-3.0
 ACL2 !>
 })

 <p>Notice that the result is displayed using @('#d') notation.  But remember
 that there are no actual floating-point objects in ACL2; @('f1') returns a
 rational logically, namely -3.  However, since the input expression is a df,
 ACL2 prints the evaluation result using @('#d') notation.  (This is analogous
 to the special printing of @('<state>') when the ACL2 state is returned, and
 similarly for user-defined stobjs.)  To see that the logical value returned is
 truly 3, note that the following event is admitted by ACL2:
 @('(thm (equal (f1 (to-df 3)) -3))').</p>

 <p>The tracking of dfs avoids Problem #1 above, that addition isn't
 associative on floating-point numbers.  That's because ACL2 does not allow
 @('+') to be applied to a df, as illustrated by the following example, which
 complains that the @('+') operation is being supplied a df, namely the call of
 @('f1').  The notion &ldquo;a result of shape :DF&rdquo; is synonymous with
 &ldquo;df&rdquo;.</p>

 @({
 ACL2 !>(+ 5 (f1 (to-df 3)))


 ACL2 Error [Translate] in TOP-LEVEL:  It is illegal to invoke F1 here
 because of a signature mismatch.  This function call returns a result
 of shape :DF where a result of shape * is required.  Note:  this error
 occurred in the context (F1 (TO-DF 3)).

 ACL2 !>
 })

 <p>There is however an operation @('df+') that can be applied to @(':DF')
 expressions.</p>

 @({
 ACL2 !>(df+ (to-df 5) (f1 (to-df 3)))
 #d2.0
 ACL2 !>
 })

 <p>In fact @('df+') automatically converts its arguments satisfying @('dfp')
 to be dfs, so the following is also legal since @('5') is converted to
 @('(to-df 5)').</p>

 @({
 ACL2 !>(df+ 5 (f1 (to-df 3)))
 #d2.0
 ACL2 !>
 })

 <p>But @('df+') is not associative; the following fails, as it should.</p>

 @({
 (thm ; FAILS!
  (implies (and (dfp x) (dfp y) (dfp z))
           (equal (df+ (df+ x y) z)
                  (df+ x (df+ y z)))))
 })

 <p>We return now to Problem #2, that the functions @('EQUAL') and @('=') are
 logically the same in ACL2 but not in raw Lisp, as seen by evaluation in raw
 Lisp, where @('(equal 1 1.0)') evaluates to @('nil') but @('(= 1 1.0)')
 evaluates to @('t').  This problem is avoided by our syntactic tracking of df
 expressions.  The following example shows that @('equal') cannot be called on
 a df expression.</p>

 @({
 ACL2 !>(equal 1 (to-df 1))


 ACL2 Error [Translate] in TOP-LEVEL:  It is illegal to invoke TO-DF
 here because of a signature mismatch.  This function call returns a
 result of shape :DF where a result of shape * is required.  Note:
 this error occurred in the context (TO-DF 1).

 ACL2 !>
 })

 <p>One cannot directly test equality of a non-df expression with a df
 expression, but one can compare equality of two df expressions, as the
 following example illustrates.  (This example also illustrates that addition
 is commutative on dfs; we will return elsewhere to this point.)</p>

 @({
 ACL2 !>(df= (df+ #d1.2 #d3.4) (df+ #d3.4 #d1.2))
 T
 ACL2 !>
 })

 <p><b>(C) Use @(see partial-encapsulate) to axiomatize floating-point
 operations while supporting evaluation.</b></p>

 <p>Next we consider how ACL2 introduces the <i>df primitives</i>, that is,
 built-in functions and macros that take or return a df.  Their calls may be
 executed by calling corresponding Common Lisp functions.  But axiomatizing
 these primitives presents a challenge since the Common Lisp language doesn't
 quite tie down the values returned by floating-point operations.  Here is a <a
 href='http://www.lispworks.com/documentation/lw71/CLHS/Body/v_featur.htm'>relevant
 quote from the Common Lisp HyperSpec</a> about the presence of a raw Lisp
 &ldquo;feature&rdquo;, @(':ieee-floating-point').</p>

 <blockquote>
 If present, indicates that the implementation purports to conform to the
 requirements of IEEE Standard for Binary Floating-Point Arithmetic.
 </blockquote>

 <p>ACL2 checks at build time that this feature is present.  However, that IEEE
 standard specifies results of operations with respect to a <i>rounding
 mode</i>.  Probably most or all Common Lisp implementations use <i>round to
 nearest even</i> as their rounding mode, but this is not guaranteed.  We work
 around this problem to some extent by introducing a constrained rounding
 function, @('df-round'), and using it to define the rational function
 primitives: addition (@('df+')), subtraction (@('df-')), multiplication
 (@('df*')), and division (@('df/')).  Transcendental functions, such as the
 sine function, are not as straightforward to define in terms of rounding.
 Although the sine function, for example, might be defined by rounding a
 sufficiently large Taylor approximation, transcendental functions are
 constrained with minimal axioms (at least for now); for example, the sine
 function is implemented by the constrained function, @('df-sin').  Over time
 some of those constraints may be strengthened, or they may even be replaced by
 definitions in terms of @('df-round').</p>

 <p>Even though the df primitives are constrained (except for the rational
 primitive functions, which are defined in terms of the constrained function
 @('df-round')), ACL2 can evaluate their calls, even during proofs.  This is
 arranged by introducing them with @(tsee partial-encapsulate), which allows
 some of the constraints to be implicit; see @(tsee partial-encapsulate).  The
 implicit constraints are based on computation; for example, when ACL2 admits
 the event @('(thm (equal (df-sin 0) 0))'), an implicit constraint guarantees
 @('(equal (df-sin 0) 0)').  There are also explicit constraints, which for
 example allow ACL2 to prove @('(dfp (df-sin x))').  We do not explain further
 here, but the interested reader is welcome to examine relevant comments in the
 ACL2 source code, for example in the @('partial-encapsulate') event that
 introduces @('df-round') in ACL2 source file @('float-a.lisp').</p>

 <p>ACL2 arranges for the host Lisp to evaluate calls of df primitives in @(see
 guard)-verified) and @(':')@(see program)-mode code.  For example, such
 evaluation of a @('df-sin') call leads to a call of @('sin') in Common Lisp.
 The following log illustrates this point and is discussed below.</p>

 @({
 ACL2 !>(defun f2 (x)
          (declare (type double-float x))
          (df-sin x))

 Since F2 is non-recursive, its admission is trivial.  We observe that
 the type of F2 is described by the theorem (RATIONALP (F2 X)).  We
 used the :type-prescription rule RATIONALP-DF-SIN-FN.

 (F2 :DF) => :DF.

 Computing the guard conjecture for F2....

 The guard conjecture for F2 is trivial to prove.  F2 is compliant with
 Common Lisp.

 Summary
 Form:  ( DEFUN F2 ...)
 Rules: ((:TYPE-PRESCRIPTION RATIONALP-DF-SIN-FN))
 Time:  0.01 seconds (prove: 0.00, print: 0.00, other: 0.00)
  F2
 ACL2 !>(trace$ f2)
  ((F2))
 ACL2 !>(trace! (sin :native t))

 TTAG NOTE: Adding ttag :TRACE! from the top level loop.
 ACL2 !>(f2 (df/ (df-pi) 2))
 1> (ACL2_*1*_ACL2::F2 884279719003555/562949953421312)
   2> (F2 1.5707963267948966)
     3> (SIN 1.5707963267948966)
     <3 (SIN 1.0)
   <2 (F2 1.0)
 <1 (ACL2_*1*_ACL2::F2 1)
 #d1.0
 ACL2 !>
 })

 <p>We see at &ldquo;@('1>')&rdquo; that evaluation arranged to pass
 a (representable) rational number (roughly, &pi;/2) to the
 executable-counterpart for @('f2') (again, for relevant background see @(see
 evaluation)).  But at &ldquo;@('2>')&rdquo;, where evaluation was passed to
 the raw Lisp function for @('f2'), that rational value was converted to the
 corresponding double-float value, which raw Lisp evaluation passed to the
 Common Lisp function @('sin'), at &ldquo;@('3>')&rdquo;.  Common Lisp then
 returned 1.0 for the raw Lisp applications of @('sin') and @('f2'), so that
 finally, the executable-counterpart for @('f2') returned the rational number,
 1.  That value was displayed using @('#d') notation because a call of @('f2')
 is a df.</p>

 <p>Since rounding (to nearest even, in particular) is not tied down by the
 Common Lisp language, different host Lisp implementations may give different
 results.  This leads us to the following point of emphasis.</p>

 <blockquote>
 When a collection of books is certified (see @(see certify-book)), the same
 environment &mdash; in particular the Lisp implementation and operating system
 &mdash; should be used for all of these books, even those included during
 certification.
 </blockquote>

 <p>Otherwise there is a soundness issue.  One might prove, say,
 @('(equal (df-sin 1) A)') and @('(equal (df-sin 1) B)') for distinct (but
 close by) numeric values @('A') and @('B') in two different books, certified
 with ACL2 executables built on different Lisps, and then include those two
 books to prove a contradiction.</p>

 <h3>Section 4: Syntactic Restrictions</h3>

 <p>We now present more details on the syntactic restrictions pertaining to df
 expressions (dfs).  Our discussion is still informal but it should suffice for
 the successful use of dfs in ACL2.  (Optional technical note for those familiar
 with ACL2 source function @('translate11'): a df is an expression whose
 translation is made with stobjs-out equal to @('(:DF)'), and the arguments of
 a function call are those in a @(':DF') position with respect to that function
 symbol's stobjs-in.)</p>

 <p>These syntactic restrictions are not applied in theorem and non-executable
 contexts, in particular not within @(see defthm), @(see thm), and @(tsee
 defun-nx) events and not within a call of @(tsee non-exec).  Below we focus on
 restrictions for a @(tsee defun) event, including its body, guard, and
 measure; but these restrictions also apply to @(tsee defmacro) events, @(tsee
 defconst) events, and top-level evaluation.</p>

 <p>Certain variables may be specified as dfs at the top level in the case of
 @('defun') events but not in other cases.  For a @('defun') event, the
 <i>declared dfs</i> consist of all variables @('vi') listed either in a @(tsee
 declare) form @('(type double-float v1 ... vk)') or an @(tsee xargs)
 declaration @(':dfs (v1 ... vk)').  If @('k') is @('1') then one may write
 @(':dfs v1') to abbreviate @(':dfs (v1)').  These declared dfs are the
 <i>known df variables</i> at the top level of the user-supplied body, guard,
 and measure of @('f').  The rules below indicate, for a set @('V') of
 known df variables, when an expression is a df with respect to @('V'); and
 these rules also speak to legality of certain expressions.</p>

 <p>Before presenting those rules, we extend the notion of a df
 expression (again, df for short) to that of a <i>df{i}
 expression</i> (<i>df{i}</i> for short).  Such an expression is one that
 returns multiple values when the ith value is to be considered a df.  For
 example, the expression @('(mv (to-df x) (df- y) 17)') is a df{0} expression
 and a df{1} expression but not a df{2} expression.  Note that an expression
 that returns a single value might or might not be a df expression, but it is
 never a df{i} expression for any i; and similarly, an expression that returns
 multiple values maybe a df{i} expression for various i but it is never a df
 expression.</p>

 <p>Here are the rules promised above.  They are not complete; for example,
 they do not cover @(tsee stobj-let) expressions.  But those and other cases
 should present no surprises in practice.  Let @('u') be a user-supplied
 term (that is, an <i>untranslated</i> term; see @(see term)).</p>

 <ul>

 <li>If @('u') is a variable, then @('u') is a df with respect to @('V') if and
 only if it is in @('V').</li>

 <li>If @('u') is a constant symbol then it is not a df (with respect to any
 set).</li>

 <li>If @('u') is a @(tsee lambda) expression, then @('u') is a df with respect
 to @('V') if and only if the corresponding @(tsee let) expression is a df with
 respect to @('V').</li>

 <li>If @('u') is a macro call @('(m t1 ... tn)'), then @('u') is a df with
 respect to @('V') if and only if the single-step macroexpansion of @('u') is a
 df with respect to @('V').</li>

 <li>Suppose @('u') is the term @('(f t1 ... tn)') where @('f') is a function
 symbol.  It is required that @('ti') is a df with respect to @('V') if and
 only if the @('i')th formal of @('f') is a declared df of @('f').  An
 exception to that requirement is when @('f') is @('dfp'), in which case the
 only restriction on @('t1') is that it is not a stobj name.  If @('f') returns
 a single value then @('u') is a df (respectively, df{i}) with respect to
 @('V') if and only if the body of @('f') is a df (respectively, df{i}) with
 respect to @('V').</li>

 <li>Consider @('(let ((x1 e1) ... (xk ek)) dcl1 ... dclm body)').  The rules
 apply to each @('ei') with respect to @('V'), but for @('body') the rules
 apply with respect to the following new set of known dfs.  First, remove all
 @('xi') from @('V') except when @('xi') is declared as a df in one of the
 @('dcli') with a @('double-float') type declaration.  For any @('xi') not so
 declared, ACL2 guesses whether or not @('ei') is a df with respect to @('V').
 If the guess is &ldquo;yes&rdquo; then add @('xi') as a known df, and if the
 guess is &ldquo;no&rdquo; then do not add it.  Otherwise, the guess fails to
 yield an answer, in which case ACL2 can try both ways: first it attempts to
 treat (technically, translate) @('ei') as a non-df and, if that fails, it
 treats @('ei') as a df.  (However, the guess almost always works; in
 particular, for a function call it just looks up the function's signature,
 except for a recursive call of a function being defined.)</li>

 <li>For @('(mv-let (x1 ... xk) mv-expr dcl1 ... dclm body)'), the rules apply
 to @('mv-expr') and to @('body'), but for @('body') the known dfs are modified
 as follows.  ACL2 attempts to determine those i &le; k for which @('mv-expr')
 is a df{i} expression.  (Optional technical note for those familiar with ACL2
 source function @('translate11'): ACL2 attempts to determine suitable
 stobjs-out for translation of @('mv-expr').)  Then to obtain the known dfs for
 @('body'), each @('xi') is initially removed from @('V') except for those
 @(see declare)d in some @('dcli') as having type @('double-float'), and then
 those @('xi') for which @('mv-expr') is a df{i} expression are added back as
 known dfs for translation of @('body').</li>

 </ul>

 <p>Note that ACL2 features that naturally traffic in ordinary ACL2 values may
 disallow uses of df expressions (much as they disallow uses of @(see stobj)s).
 Here are a few examples.</p>

 <ul>

 <li>A @(see table) guard must return an ordinary value, not a df.</li>

 <li>A @(see clause-processor) must return an ordinary value (and perhaps
 stobjs in the multiple-values case; see @(see clause-processor)).</li>

 <li>A @(see theory) expression, as well as the argument of @(tsee defconst),
 @(tsee defpkg), @(tsee syntaxp), or @(tsee bind-free), must return an ordinary
 value, not a df.</li>

 </ul>

 <h3>Section 5: Guards</h3>

 <p>When a @(tsee defun) event defines a function, the @(see guard) for that
 function asserts that @('dfp') holds for each declared df.  Here's an
 example</p>

 @({
 (defun df-10/x (x)
   (declare (xargs :guard (not (df= 0 x))
                   :dfs x))
   (df/ 10 x))
 })

 <p>The generated guard is @('(and (dfp x) (not (df= 0 x)))').  Note that
 @('(dfp x)') precedes @('(not (df= 0 x))'): the conjuncts generated from the
 @(':dfs') always precede those that come from @(':guard') specifications.</p>

 <p>Instead of specifying declared dfs using @(':dfs') @(tsee xargs), a better
 approach (see Section 7: Remarks on performance) is to use @('double-float')
 @(tsee type) declarations.  Here's a variant of the example above that uses
 this approach; it too is admitted by ACL2.</p>

 @({
 (defun df-10/x (x)
   (declare (xargs :guard (not (df= 0 x)))
            (type double-float x))
   (df/ 10 x))
 })

 <p>Technical remark (feel free to skip it).  There is a subtlety here.  Unlike
 @(':dfs') specifications, any @(see type) declarations are conjoined with
 @(':guard') specifications in the order of appearance of each.  (This is a
 general aspect of ACL2, not specific to @('double-float') types.)  So in the
 example above, the guard is essentially @('(and (not (df= 0 x)) (dfp x))').
 It may be surprising that @('(df= 0 x)') can itself be guard-verified without
 the assumption of @('(dfp x)').  The reason is that ACL2 figures out that
 @('x') is a declared df, and deduces that since this is legal code, we know
 that @('(dfp x)') is true.</p>

 <h3>Section 6: Df primitives</h3>

 <p>This section documents the df primitives, which (again) are those built-in
 functions and macros that take or return a df.  A small number of related
 built-ins are also documented here.  These are divided here into the following
 groups.</p>

 <ul>
 <li>Recognizers and conversion functions</li>
 <li>Basic arithmetic operations</li>
 <li>Other operations</li>
 </ul>

 <p>In each case, we display a function's signature (as in the example of
 @('f2') above) and describe its functionality.  You can of course use
 @(':')@(tsee pe) to see its logical definition.</p>

 <p>But first we discuss a class of convenient macros.</p>

 <p><u>Corresponding df-friendly macros</u></p>

 <p>Before we document the df primitive functions, we describe corresponding
 macros that automatically convert certain constants to df expressions by using
 a @('to-df') wrapper.  We call such a macro the &ldquo;corresponding
 df-friendly macro&rdquo; for the given function.  Below, we show how that
 works for @('binary-df+') and its corresponding df-friendly macro, @('df+').
 The same relationship holds for other df primitive functions and their
 corresponding df-friendly macros.</p>

 <p>Consider the following examples of adding two dfs with the function
 @('binary-df+').</p>

 @({
 ACL2 !>(binary-df+ (to-df 3) (to-df 1/2))
 #d3.5
 ACL2 !>(let ((x (to-df 3))) (binary-df+ x (to-df 1/2)))
 #d3.5
 ACL2 !>
 })

 <p>The arguments to @('binary-df+') must be dfs, so it is illegal to remove
 any call of @('to-df') above.  For example, all of the following cause
 errors.</p>

 <ol>

 <li>@('(binary-df+ 3 1/2)') <i>; 3 and 1/2 are not dfs</i></li>
 <li>@('(let ((x (to-df 3))) (binary-df+ x 1/2))') <i>; 1/2 is not a
 df</i></li>
 <li>@('(let ((x 3)) (binary-df+ x (to-df 1/2)))') <i>; x is not a df</i></li>

 </ol>

 <p>However, @('binary-df+') has a corresponding df-friendly macro, @('df+').
 That macro expands to a call of @('binary-df') with a call of @('to-df')
 wrapped around every constant numeric argument that satisfies @('dfp').  The
 following calls show expansions of @('df+') calls that correspond to calls
 from the first two examples above.</p>

 @({
 ACL2 !>:trans1 (df+ 3 1/2)
  (BINARY-DF+ (TO-DF 3) (TO-DF 1/2))
 ACL2 !>:trans1 (df+ x 1/2)
  (BINARY-DF+ X (TO-DF 1/2))
 ACL2 !>
 })

 <p>So, evaluation succeeds for those two uses of @('df+') in place of
 @('binary-df+').</p>

 @({
 ACL2 !>(df+ 3 1/2)
 #d3.5
 ACL2 !>(let ((x (to-df 3))) (df+ x 1/2))
 #d3.5
 ACL2 !>
 })

 <p>The third example still fails, however, since @('df+') only wraps
 @('to-df') around constants.</p>

 @({
 ACL2 !>(let ((x 3)) (df+ x (to-df 1/2)))


 ACL2 Error [Translate] in TOP-LEVEL:  The form X represents an ordinary
 object, but it is being used where a form representing a :DF was expected.
 See :DOC df.  Note:  this error occurred in the context
 (BINARY-DF+ X (TO-DF 1/2)).

 ACL2 !>
 })

 <p>Note that a constant value is only supplied a @('to-df') wrapper when it
 satisfies @('dfp'), that is, it is a representable rational, as illustrated by
 the following example.</p>

 @({
 ACL2 !>:trans1 (df+ 1/3 1/4)
  (BINARY-DF+ 1/3 (TO-DF 1/4))
 ACL2 !>
 })

 <p>The focus above has been on numeric constants, but symbolic constants that
 start and end with the &lsquo;@('*')&rsquo; character, like @('*c*'), are
 treated somewhat similarly.  Such an argument of a df-friendly macro is given
 a @('to-df') wrapper as well as an assertion that @('dfp') holds.  Suppose for
 example that we submit the following two events.</p>

 @({
 (defconst *good* 1/4) ; 1/4 satisfies dfp.
 (defconst *bad* 1/3)  ; 1/3 does not satisfy dfp.
 })

 <p>Here is how those arguments are treated when supplied to a df-friendly
 macro.</p>

 @({
 ACL2 !>:trans1 (df+ *good* *bad*)
  (BINARY-DF+ (LET ((C *GOOD*))
                (ASSERT$ (DFP C) (TO-DF C)))
              (LET ((C *BAD*))
                (ASSERT$ (DFP C) (TO-DF C))))
 ACL2 !>
 })

 <p>Indeed, evaluation of @('(df+ *good* *bad*)') results in an assertion
 failure.</p>

 @({
 HARD ACL2 ERROR in ASSERT$:  Assertion failed:
 (ASSERT$ (DFP C) (TO-DF C))
 })

 <p>But logically, @(tsee assert$) returns its second argument, so ACL2 can
 prove the following.</p>

 @({
 (equal (df+ *good* *bad*)
        (binary-df+ *good* (to-df *bad*)))
 })

 <p><u>Recognizers and conversion functions</u></p>

 <p>@('(from-df :DF) => *')<br/>
 Converts a df to a numerically equivalent ordinary value.</p>

 <p>@('(to-df *) => :DF')<br/>
 Converts an ordinary value to a nearby df.  This is the identity on any
 rational that is representable by a floating-point number.</p>

 <p>@('(to-dfp *) => *')<br/>
 This is logically the same as @('to-df'), but it returns an ordinary value
 rather than a df.</p>

 <p>@('(dfp {* or :DF}) => *')<br/>
 Recognizes rationals that can be represented by Lisp double-floats; so, always
 true when applied to a df.  The logical definition of @('(dfp x)') is
 @('(and (rationalp x) (= (to-df x) x))').</p>

 <p>@('(df-round *) => *')<br/>
 Constrained, non-executable rounding function, which converts a rational to a
 nearby value that satisfies @('dfp').  It is used in the definitions of the
 basic arithmetic operations.</p>

 <p>@('(df-string :DF) => *')<br/>
 Produces the floating-point representation, as a string, of the given df
 value.  Examples:</p>

 @({
 ACL2 !>(df-string (to-df 1/4))
 "0.25"
 ACL2 !>(df-string (to-df 1/3))
 "0.3333333333333333"
 ACL2 !>
 })

 <p>@('(df-rationalize-fn :DF) => *')<br/>
 Calls the Common Lisp function, @('rationalize'), which the Common Lisp
 HyperSpec says &ldquo;returns a rational that approximates the float to the
 accuracy of the underlying floating-point representation.&rdquo;  The idea is
 to produce a &ldquo;pretty&rdquo; rational that approximates the given df, as
 illustrated by the following example.</p>

 @({
 ACL2 !>(from-df (to-df 1/10))
 3602879701896397/36028797018963968
 ACL2 !>(df-rationalize (to-df 1/10))
 1/10
 ACL2 !>
 })

 <p>@('(rize *) => *')<br/>
 This is a variant of @('df-rationalize') that operates on rationals instead of
 dfs, as shown by the following extension of the example just above.</p>

 @({
 ACL2 !>(rize 3602879701896397/36028797018963968)
 1/10
 ACL2 !>
 })

 <p><u>Basic arithmetic operations</u></p>

 <p>@('(binary-df+ :df :df) => :df')<br/>
 Adds the two given dfs.<br/>
 Corresponding df-friendly macro: @('(df+ x y )')</p>

 <p>@('(binary-df* :df :df) => :df')<br/>
 Multiplies the two given dfs.<br/>
 Corresponding df-friendly macro: @('(df* x y )')</p>

 <p>NOTE: Both @('df+') and @('df*') are binary, unlike @('+') and @('*').  An
 immediate issue is that the failure of associativity could cause a divergence
 with the logical expansion into a right-associated sum or product, for example
 in raw Lisp as follows.</p>

 @({
 ? (+ .1 .2 .3)
 0.6000000000000001
 ? (+ .1 (+ .2 .3))
 0.6
 ?
 })

 <p>@('(binary-df/ :df :df) => :df')<br/>
 Divides the two given dfs, where the second should be non-zero.<br/>
 Corresponding df-friendly macro: @('(df/ x y )')</p>

 <p>@('(unary-df- :df) => :df')<br/>
 Takes the negative of the given df.<br/>
 Corresponding df-friendly macro: @('(df- x)')</p>

 <p>@('(unary-df/ :df) => :df')<br/>
 Takes the reciprocal of the given non-zero df.<br/>
 Corresponding df-friendly macro: @('(df/ x)')</p>

 <p>Also provided is a binary version of the macro @('df-').  The expansion of
 @('(df- term1 term2)') is essentially @('(df+ term1 (df- term2))').</p>

 <p>These functions are all defined by applying @('df-round') to the exact
 mathematical result.  Here are their definitions in the ACL2 logic.</p>

 @(def binary-df+)
 @(def binary-df*)
 @(def binary-df/)
 @(def unary-df-)
 @(def unary-df/)

 <p>We include the following as a basic arithmetic operation (though some may
 argue with that classification).</p>

 <p>@('(df-abs-fn :df) => :df')<br/>
 Return the absolute value of the df input, as a df.<br/>
 Corresponding df-friendly macro: @('(df-abs x)')</p>

 <p><u>Other operations</u></p>

 <p>These are listed alphabetically.  They include the square root function and
 common transcendental functions.  The first two are logarithm functions.</p>

 <p>@('(binary-df-log :df :df) => :df')<br/>
 Takes the log, where the first argument is the base.<br/>
 Corresponding df-friendly macro: @('(df-log x y)')</p>

 <p>@('(unary-df-log :df) => :df')<br/>
 Takes the natural log (log base @('e')) of the given df.<br/>
 Corresponding df-friendly macro: @('(df-log x)')</p>

 <p>The following zero-ary functions return floating-point constants.</p>

 <p>@('(df-pi) => :df')<br/>
 Returns a df approximation to &pi;.<br/>
 The constant @('*df-pi*') is defined to be the corresponding rational:<br/>
 @('(defconst *df-pi* (from-df (df-pi)))').</p>

 <p>@('(df0) => :df')<br/>
 Returns a df logically equal to 0.</p>

 <p>@('(df1) => :df')<br/>
 Returns a df logically equal to 1.</p>

 <p>@('(df-minus-1) => :df')<br/>
 Returns a df logically equal to -1.</p>

 <p>The remaining functions are listed in alphabetic order.  Each has a name of
 the form @('df-NAME-fn') where @('NAME') is the name of a corresponding Common
 Lisp function.  Each takes a df argument except for @('expt'), which takes two
 df arguments, and each returns a df argument.  The guards require not only
 @('dfp') of each argument but the extra conditions as shown below.  Each has a
 corresponding df-friendly macro, @('df-NAME').</p>

 <dl>
 <li>@('(df-acos-fn x)') ; guard extra: @('(df<= (df-abs-fn x) 1)')</li>
 <li>@('(df-acosh-fn x)')</li>
 <li>@('(df-asin-fn x)')</li>
 <li>@('(df-asinh-fn x)')</li>
 <li>@('(df-atan-fn x)')</li>
 <li>@('(df-atanh-fn x)') ; guard extra: @('(df< (df-abs x) 1)')</li>
 <li>@('(df-cos-fn x)')</li>
 <li>@('(df-cosh-fn x)')</li>
 <li>@('(df-exp-fn x)')</li>
 <li>@('(df-expt-fn x y)') ; guard extra: @('(or (df< 0 x) (and (df= 0 x) (df< 0 y)))')</li>
 <li>@('(df-sin-fn x)')</li>
 <li>@('(df-sinh-fn x)')</li>
 <li>@('(df-sqrt-fn x)') ; guard extra: @('(df<= 0 x)')</li>
 <li>@('(df-tan-fn x)') ; guard extra: @('(not (df= (df-cos-fn x) 0))')</li>
 <li>@('(df-tanh-fn x)') ; guard extra: @('(not (df= (df-cosh-fn x) 0))')</li>
 </dl>

 <h3>Section 7: Remarks on performance</h3>

 <p>This section covers just a few aspects of performance pertaining to the use
 of dfs.  Those who use dfs and can provide useful performance tips are
 welcomed to extend this section.</p>

 <p><u>Inlining of df primitives</u></p>

 <p>Suppose we start ACL2 and then submit the following forms, which define
 @('g1') in raw Lisp and provide its assembly code.</p>

 @({
 (defun g1 (x y) (declare (type double-float x y)) (df< x y))
 (disassemble 'g1)
 })

 <p>If we repeat this experiment in a new ACL2 session except that we replace
 @('df<') with @('<'), we get the same assembly code (at least, when using ACL2
 built on CCL or on SBCL as of this writing).  This is good; it shows that
 there is no performance penalty for using @('df<').  To understand why, first
 observe that macroexpansion replaces @('df<') by @('df<-fn'); then observe
 that the ACL2 sources include a @('declaim') form that declares @('df<-fn') to
 be inline.  All the df primitive functions are similarly declared inline
 except for @('to-df'), which we discuss next.  Of course, these inlined raw
 Lisp functions (and macro) cannot generally be @(see trace)d.</p>

 <p><u><tt>To-df</tt></u><u> is a macro in raw Lisp</u></p>

 <p>Although @('to-df') is a function in the ACL2 logic, it is implemented as a
 macro in raw Lisp.  To see how that benefits performance, consider the
 following definition.</p>

 @({
 (defun add3 (x) (declare (type double-float x)) (df+ 3 x))
 })

 <p>We can see the translation of that @('df+') call as follows.</p>

 @({
 ACL2 !>(body 'add3 nil (w state))
 (BINARY-DF+ (TO-DF '3) X)
 ACL2 !>
 })

 <p>Since @('binary-df+') is inlined in raw Lisp (see above), its call above
 essentially equivalent in raw lisp to @('(+ (TO-DF '3) X)').  But it would be
 unfortunate to call to-df at runtime, even if @('to-df') were an inlined
 function.</p>

 <p>However, @('to-df') is a macro that expands away its call on a rational
 argument or quoted rational argument.</p>

 @({
 ? (macroexpand-1 '(TO-DF '3))
 3.0
 T
 ?
 })

 <p>A key performance tip is that a @('defun') form should @(see declare) dfs
 with a type declaration rather than an @('xargs :dfs') declaration.  Here are
 examples.</p>

 <p><u>Type declarations are probably preferred</u></p>

 <p>This observation is not really specific to the use of dfs.  Common Lisp
 compilers can sometimes take advantage of @('type') @(see declaration)s, but
 they never take advantage of @('xargs') declarations (because those are
 ignored by the compiler).  So just as one may get better performance with a
 declaration @('(type (integer 0 *) x)') than with @('(xargs :guard (natp
 x))'), one may get better performance with (declare (type double-float x))
 than with @('(xargs :dfs x)').</p>

 <h3>Section 8: More examples</h3>

 <p>This section, which forms the remainder of this topic, is a synopsis of
 @(see community-books) file @('books/demos/floating-point-input.lsp').  It may
 be useful to skip this section and instead read that file; or one could
 consult that file when an example given below needs more explanation, since
 other examples in that file may be clarifying.  Comments in that file may
 suffice to explain what is going on, but if not, then corresponding output
 file @('books/demos/floating-point-log.txt') (generated by the @(see
 run-script) utility) may be worth a look.</p>

 <p>Here are the contents of that file (quoting from a comment near its
 top).</p>

 @({
 ;;; TABLE OF CONTENTS
 ;;; -----------------
 ;;; "Floats" as rationals
 ;;; Overflow and underflow
 ;;; An assertion macro
 ;;; Df-rationalize and rize
 ;;; More on dfp & to-df (recognizer & generator for representables)
 ;;; Fun with pi
 ;;; No support for complex floats
 ;;; Examples with defined functions
 ;;; Examples focused on ec-call
 ;;; We can't prove much
 ;;; Df stobj fields
 ;;; Arrays of double-floats
 ;;; DO loop$ expressions
 ;;; FOR loop$ expressions
 ;;; Stobj-let (nested stobjs)
 ;;; Using apply$ with dfs, including efficiency issues
 ;;; Encapsulate and signatures
 ;;; Memoization
 ;;; Miscellany
 ;;; Check consistency with values produced in raw Lisp
 })

 <p>We now hit some highlights of each of those sections that may not have been
 adequately covered above.  See @('books/demos/floating-point-input.lsp') for
 more details, e.g., the use of either @('E') or @('D') as an exponent
 marker.</p>

 <p><i>;;; "Floats" as rationals</i></p>

 @({
 (assert-event
 ; 31/10 is not representable, but every #d number that is read without
 ; error is representable -- hence the equality below is false.
  (not (equal #d3.1 31/10)))

 (assert-event (equal #d1d50 #d1.0E50)) ; Both are the same rational.

 ; The following are not quite equal because the latter is not representable.
 (assert-event (not (equal #d1d50 (expt 10 50))))

 (assert-event
  (let ((x (to-df #d.1))
        (y (to-df #d.2))
        (z (to-df #d.3)))
    (not (df= (df+ (df+ x y) z)
              (df+ x (df+ y z))))))
 })

 <p><i>;;; Overflow and underflow</i></p>

 @({
 #d1E310 ; Lisp error (overflow)

 #d1E-500 ; 0 (underflow)
 (to-df #d1E-500) ; #d0.0 (underflow)
 })

 <p><i>;;; An assertion macro</i></p>

 <blockquote>
 <p>This section just defines a macro, @('a-e'), which checks that its input is
 true in two ways: by direct evaluation and by proof.</p>
 </blockquote>

 <p><i>;;; Df-rationalize and rize</i></p>

 @({
 (thm (equal (to-df 1/3) ; Rational representation is on next line.
             6004799503160661/18014398509481984))

 (df-rationalize
  (to-df 1/3)) ; result is 1/3

 (rize 1/3) ; 1/3; equivalent to (df-rationalize (to-df 1/3)) above
 })

 <p><i>;;; More on dfp &amp; to-df (recognizer &amp; generator for representables)</i></p>

 @({
 (a-e (equal (dfp 1/4) t)) ; 1/4 is representable
 (a-e (equal (dfp 1/3) nil)) ; 1/3 is not representable
 (a-e ; to-df maps a rational to one that's representable
  (equal (dfp (to-df 1/3)) t))
 (thm (equal (to-df 'abc) 0)) ; default guard-violating behavior
 })

 <p><i>;;; Fun with pi</i></p>

 @({
 (defconst *2pi*
 ; See also df-2pi.  This is a rational approximation to 2*pi.  Note
 ; that *df-pi* is already defined as a rational approximation to pi.
 ; Both *df-pi* and *2pi* are ordinary objects, not dfs; defconst
 ; always creates an ordinary object.
   (* 2 *df-pi*))

 ; Signature shows return of :DF in the following.
 (defun-inline df-2pi ()
 ; See also *2pi*.  Here, however, we return a :df (which is a
 ; double-float in raw Lisp) rather than an ordinary object.  Note that
 ; since (df-pi) is representable, multiplying it by 2 produces a
 ; representable rational as well (since that multiplication keeps the
 ; mantissa and simply doubles the small exponent).
   (df* 2 (df-pi)))

 (a-e
 ; This holds since *df-pi* = (df-pi) and (df-2pi) is just the exact
 ; product by 2 of (df-pi), as noted above.
  (equal *2pi* (from-df (df-2pi))))

 (df-sin (df-2pi)) ; very near 0, but not 0 (floating-point sin is not exact)
 })

 <p><i>;;; No support for complex floats</i></p>

 @({
 (to-df #c(0 1)) ; guard violation (expects a rational)
 })

 <p><i>;;; Examples with defined functions</i></p>

 <blockquote>
 <p>This section of @('books/demos/floating-point-input.lsp') has several
 examples that are worth reading if you have difficulties defining functions
 that traffic in dfs.  In particular, it shows how to use @('THE') (see @(see
 the)) with a @('double-float') @(see type-spec) to assist ACL2 with its syntax
 checking.</p>
 </blockquote>

 <p><i>;;; Examples focused on ec-call</i></p>

 <blockquote>
 <p>The example below shows the need to add a @(':dfs') argument to @(tsee
 ec-call) when the call returns a df.  See this section in
 @('books/demos/floating-point-input.lsp') for additional discussion and
 examples.</p>
 </blockquote>

 @({
 (defun f6 (x)
   (declare (xargs :guard (rationalp x)))
   (ec-call (unary-df- (to-df x))
            :dfs-in '(t)
            :dfs-out '(t)))
 })

 <p><i>;;; We can't prove much</i></p>

 <blockquote>
 <p>This section of @('books/demos/floating-point-input.lsp') gives some
 examples of what can be proved about df operations and what cannot be
 proved.</p>
 </blockquote>

 <p><i>;;; Df stobj fields</i></p>

 @({
 (defstobj st1
   (accum :type double-float :initially 0))

 (assert-event (df= (accum st1) 0))

 (update-accum (to-df 3) st1)

 (assert-event (df= (accum st1) 3))
 })

 <p><i>;;; Arrays of double-floats</i></p>

 @({
 (defstobj st3
 ; Here is an array of double-floats.  The implementation will, as
 ; usual, take into account the array element type (here, double-float)
 ; when reading or writing the array, by generating suitable type
 ; declarations.
 ; NOTE: It may be that code runs faster (but using more space) if the raw Lisp
 ; array is declared to have elements of type t instead of type double-float.
 ; Such a change might be considered in the future.
   (ar :type (array double-float (8)) :initially 0))

 (defun load-ar (i max lst st3)
 ; Update the ar field of st3 with the values in lst, starting at position i.
   [[.. elided here; see books/demos/floating-point-input.lsp ..]])

 (load-ar 0 8 (list 3 0 *df-pi* 3/4 -2/3 5 -6 7) st3)

 (assert-event (and (= (from-df (ari 2 st3)) *df-pi*)
                    (= (from-df (ari 6 st3)) -6)
                    (df= (ari 6 st3) -6)
                    (df< (ari 0 st3) 5)))

 (defthm dfp-nth-arp
 ; a useful lemma
   (implies (and (arp ar)
                 (natp i)
                 (< i (len ar)))
            (dfp (nth i ar))))

 ; We can read dfs and update with dfs.
 (defun scalar-multiply-ar (i mult st3)
   (declare (xargs :stobjs st3
                   :guard (and (natp i) (<= i 8)))
            (type double-float mult))
   (cond ((zp i) st3)
         (t (let* ((i (1- i))
                   (old (ari i st3))
                   (st3 (update-ari i (df* mult old) st3)))
              (declare (type double-float old))
              (scalar-multiply-ar i mult st3)))))

 (defun scalar-multiply-ar-example (st3)
    (declare (xargs :stobjs st3))
    (scalar-multiply-ar 4 (to-df 4) st3))

 (load-ar 0 8 (list 3 0 *df-pi* 3/4 -2/3 5 -6 7) st3)

 (scalar-multiply-ar-example st3)

 (assert-event (and (= (from-df (ari 2 st3)) (* 4 *df-pi*))
                    (= (from-df (ari 6 st3)) -6)
                    (df= (ari 6 st3) -6)
                    (df< (ari 0 st3) 20)))
 })

 <p><i>;;; DO loop$ expressions</i></p>

 <blockquote>
 <p>This section of @('books/demos/floating-point-input.lsp') continues using
 the stobj from the preceding section to show how @('DO') @(tsee loop$)
 expressions can operate on a stobj array.</p>
 </blockquote>

 <p><i>;;; FOR loop$ expressions</i></p>

 @({
 ; The following is illegal, because it is illegal to use a df variable (in this
 ; case, w) in a FOR loop$ expression.  Use DO loop$ expressions instead in such
 ; cases, as illustrated in the preceding section.
 (let ((w (to-df 7)))
   (loop$ for v from 1 to 3
          sum (from-df (df+ w (to-df v)))))
 })

 <p><i>;;; Stobj-let (nested stobjs)</i></p>

 <blockquote>
 <p>This section of @('books/demos/floating-point-input.lsp') shows that the
 @(tsee stobj-let) utility works properly with dfs.</p>
 </blockquote>

 <p><i>;;; Using apply$ with dfs</i></p>

 @({
 ; We see in examples below that apply$ works with df arguments.  This may seem
 ; surprising.  After all, there is a similar prohibition on stobj arguments
 ; because a stobj cannot be put into a list; wouldn't such a prohibition
 ; similarly pertain to df arguments, since they too cannot be put into a list?

 ; However, ACL2 evaluation of apply$ calls takes place by calling *1*
 ; functions, and these tolerate ordinary rational inputs where dfs are
 ; expected.  So apply$ accepts rational arguments where dfs are expected,
 ; provided they satisfy dfp.

 (defun f0 (x)
   (declare (xargs :verify-guards nil)
            (type double-float x))
   (df- x))

 ; This too is redundant (already included above).
 (include-book "projects/apply/top" :dir :system)

 ; "Teach" apply$ about f0:
 (defwarrant f0)

 ; Succeeds, since 1/4 satisfies the guard for f0, (dfp x).
 (assert-event (equal (apply$ 'f0 (list 1/4))
                      -1/4))

 ; Same as above, since the #d quantities are just rationals:
 (assert-event (equal (apply$ 'f0 (list #d0.25))
                      #d-0.25))

 ; Error: guard violation, since (dfp 1/3) is false.
 (apply$ 'f0 (list 1/3))

 ;;; Efficiency issues when using apply$ with dfs</i></p>
 [[.. Examples omitted here; see books/demos/floating-point-input.lsp. ..]]
 })

 <p><i>;;; Encapsulate and signatures</i></p>

 @({
 (encapsulate
   (((f16 *) => :df :formals (x) :guard (rationalp x)))
   (local (defun f16 (x)
            (declare (ignore x))
            (to-df 0))))

 (defstub f19 (:df) => (mv :df :df))
 })

 <p><i>;;; Memoization</i></p>

 @({
 ; Memoization works fine with dfs; the subtleties when memoizing with stobjs
 ; don't apply to dfs.
 })

 <p><i>;;; Miscellany</i></p>

 @({
 ; The following defun-sk is accepted, even though y represents an ordinary
 ; object, because by default the defun-sk function is non-executable.
 (defun-sk f25 (x)
   (declare (xargs :dfs (x)))
   (exists (y) (df< x y)))

 ;;; Memoize-partial works fine with dfs.
 })

 <p><i>;;; Check consistency with values produced in raw Lisp</i></p>

 @({
 ; This section has tests to check that ACL2 evaluation with dfs agrees with
 ; corresponding Common Lisp evaluation on double-floats.
 })

 <h3>Section 9: Remarks for system programmers</h3>

 <p>Probably most ACL2 users should skip this section.  But those who use
 ACL2 system utilities (see for example @(see system-utilities) and @(see
 programming-with-state)) may find some remarks here to be useful.</p>

 <p>The functions @('translate'), @('translate1'), @('translate-cmp'), and
 @('translate1-cmp') all convert a user-level @(see term) to a translated
 term.  Each of these assumes that no free variable of the user-level term is a
 df.  The function @('translate1-cmp+') has an extra argument, @('known-dfs'),
 that is a list of free variables that are to be considered to be dfs.</p>

")

(defxdoc digit-char-p
  :parents (characters acl2-built-ins)
  :short "The number, if any, corresponding to a given character"
  :long "<p>@('(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).</p>

 <p>The @(see 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.</p>

 <p>@('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.</p>

 @(def digit-char-p)
 @(def our-digit-char-p)")

(defxdoc digit-to-char
  :parents (characters acl2-built-ins)
  :short "Map a digit to a character"
  :long "@({
  Example:
  ACL2 !>(digit-to-char 8)
  #\8
 })

 <p>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.</p>

 <p>The @(see guard) for @('digit-to-char') requires its argument to be an
 integer between 0 and 15, inclusive.</p>

 @(def digit-to-char)")

(defxdoc dimensions
  :parents (arrays acl2-built-ins)
  :short "Return the @(':dimensions') from the @(see header) of a 1- or
  2-dimensional array"
  :long "@({
  Example Form:
  (dimensions 'delta1 a)

  General Form:
  (dimensions name alist)
 })

 <p>where @('name') is arbitrary and @('alist') is a 1- or 2-dimensional array.
 This function returns the dimensions list of the array @('alist').  That list
 will either be of the form @('(dim1)') or @('(dim1 dim2)'), depending on
 whether @('alist') is a 1- or 2-dimensional array.  @('Dim1') and @('dim2')
 will be integers and each exceed by 1 the maximum legal corresponding index.
 Thus, if @('dimensions') returns, say, @(''(100)') for an array @('a') named
 @(''delta1'), then @('(aref1 'delta1 a 99)') is legal but @('(aref1 'delta1 a
 100)') violates the @(see guard)s on @(tsee aref1).  @('Dimensions') operates
 in virtually constant time if @('alist') is the semantic value of @('name').
 See @(see arrays).</p>

 @(def dimensions)")

(defxdoc disable
  :parents (theories theory-functions)
  :short "Deletes names from current theory"
  :long "@({
  Example:
  (disable fact (:e fact) associativity-of-app)

  General Form:
  (disable name1 name2 ... namek)
 })

 <p>where each @('namei') is a runic designator; see @(see theories).  The
 result is the theory that contains all the names in the current theory except
 those listed.  Note that this is merely a function that returns a theory.  The
 result is generally a very long list of @(see rune)s and you will probably
 regret printing it.</p>

 <p>For related utilities, see @(see enable) and see @(see e/d).</p>

 <p>The standard way to ``disable'' a fixed set of names, is as follows; see
 @(see hints) and see @(see in-theory).</p>

 @({
  :in-theory (disable name1 name2 ... namek)    ; in a hint
  (in-theory (disable name1 name2 ... namek))   ; as an event
  (local ; often desirable, to avoid exporting from the current context
   (in-theory (disable name1 name2 ... namek)))
 })

 <p>Note that all the names are implicitly quoted.  If you wish to disable a
 computed list of names, @('lst'), use the theory expression
 @('(set-difference-theories (current-theory :here) lst)').</p>

 <p>To see the runes currently disabled that are among those created when a
 function symbol @('FN') is introduced, evaluate @('(disabledp 'FN)').</p>")

(defxdoc disable-forcing
  :parents (force)
  :short "To disallow forced case-splits"
  :long "@({
  General Form:
  ACL2 !>:disable-forcing   ; disallow forced case splits
 })

 <p>See @(see force) and see @(see case-split) for a discussion of forced case
 splits, which are inhibited by this command.</p>

 <p>@('Disable-forcing') is actually a macro that @(see disable)s the @(see
 executable-counterpart) of the function symbol @('force'); see @(see force).
 When you want to use @(see hints) to turn off forced case splits, use a form
 such as one of the following (these are equivalent).</p>

 @({
  :in-theory (disable (:executable-counterpart force))
  :in-theory (disable (force))
 })

 <p>The following example shows how this works.  First evaluate these
 forms.</p>

 @({
  (defstub f1 (x) t)
  (defstub f2 (x) t)
  (defaxiom ax (implies (case-split (f2 x)) (f1 x)))
  (thm (f1 x))
 })

 <p>You will see the application of the rule, @('ax'), in the proof of the
 @(tsee thm) call above.  However, if you first evaluate
 @('(disable-forcing)'), then there will be no application of @('ax').  To
 restore forced case splitting, see @(see enable-forcing).</p>")

(defxdoc disable-immediate-force-modep
  :parents (force)
  :short "@(see force)d hypotheses are not attacked immediately"
  :long "@({
  General Form:
  ACL2 !>:disable-immediate-force-modep
 })

 <p>This event causes ACL2 to delay @(see force)d hypotheses to the next
 forcing round, rather than attacking them immediately.  See @(see
 immediate-force-modep).  Or for more basic information, first see @(see force)
 for a discussion of @(see force)d case splits.</p>

 <p>Disable-immediate-force-modep is a macro that @(see disable)s the @(see
 executable-counterpart) of the function symbol @(tsee immediate-force-modep).
 When you want to @(see disable) this mode in @(see hints), use a form such as
 one of the following (these are equivalent).</p>

 @({
  :in-theory (disable (:executable-counterpart immediate-force-modep))
  :in-theory (disable (immediate-force-modep))
 })")

(defxdoc disable-ubt
  :parents (history)
  :short "Make it illegal to undo back through the current @(see command)"
  :long "<p>The utility @('disable-ubt') is probably only relevant to those who
 write ACL2-based tools, in particular using @(see wormhole)s.  Its initial
 application (and perhaps still its only application) is to arrange that inside
 the @(see break-rewrite) interactive loop, it is impossible to undo the @(see
 ld-keyword-aliases) supporting the @(see brr-commands).</p>

 @({
 General Forms:

 :disable-ubt
 (disable-ubt)     ; same as above
 (disable-ubt arg) ; same as above if arg is not nil or :disable-ubt
 })

 <p>where @('arg') is evaluated, and if it is supplied and its value is neither
 @('nil') nor @(':disable-ubt'), then its value satisfies @(tsee msgp).  In
 that case, the message is printed after the usual message (except, before
 ``See :DOC disable-ubt'').  The following example illustrates the use of that
 optional message but, what is more important, it illustrates the effect of
 @('disable-ubt'): a @(see command) that executes it cannot be undone.</p>


 @({
 ACL2 !>(disable-ubt (list "Just a demo: ~x0." (cons #0 17)))

 Summary
 Form:  ( DISABLE-UBT ...)
 Rules: NIL
 Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
  :DISABLE-UBT
 ACL2 !>:ubt :x


 ACL2 Error in :UBT:  Can't undo a :disable-ubt event (at command 1).
 Just a demo: 17.  See :DOC disable-ubt.

 ACL2 !>
 })

 <p>@('Disable-ubt') is similar to @('(reset-prehistory t)'), as both establish
 a barrier to undoing.  However, for history commands such as @(':')@(tsee
 pcb), command numbers are not changed by @('disable-ubt').  Like @(tsee
 reset-prehistory), @('disable-ubt') is never @(see redundant).</p>

")

(defxdoc disabledp
  :parents (theories)
  :short "Determine whether a given name or rune is disabled"
  :long "<code>
 Examples:

 :disabledp foo   ; returns a list of all disabled runes whose base
                  ; symbol is foo (see @(see rune))
 (disabledp 'foo) ; same as above (i.e., :disabledp foo)
 :disabledp (:rewrite bar . 1) ; returns t if the indicated rune is
                               ; disabled, else nil
 (disabledp (:rewrite bar . 1)); same as immediately above
 (disabledp '(:definition binary-append))
     ; returns t if the indicated definition is disabled, else nil
 (disabledp '(:d append))
     ; same as above
 </code>

 <p>Also see @(see pr), which gives much more information about the rules
 associated with a given event.</p>

 <p>@('Disabledp') takes one argument, which is a symbol, a @(see rune), or a
 runic abbreviation such as @('(:d append)') (see @(see theories)).  In the
 former case it returns the list of disabled runes associated with that name,
 in the sense that the rune's ``base symbol'' is that name (see @(see rune))
 or, if the event named is a @(tsee defmacro) event, then the list of disabled
 runes associated with the function corresponding to that macro name, if
 any (see @(see macro-aliases-table)).  In the other cases, where the argument
 is a @(see rune) or a runic abbreviation for a rune, @('disabledp') returns
 @('t') if the rune is disabled, and @('nil') otherwise.</p>

 <p>Remark for users of the @(see break-rewrite) utility.  Inside the
 @(':')@(tsee brr) loop, the computation performed by @('disabledp') takes
 place with respect to the state of the proof that is currently underway,
 rather than the global state.  For example, if you break while the prover is
 working on Subgoal 3, and the @(see hints) supplied for the proof specify
 @('("Subgoal 3" :in-theory (disable foo))'), then @('disabled') will
 return the runes associated with @('foo'), regardless of whether or not those
 runes are disabled globally.</p>")

(defxdoc disassemble$
  :parents (compilation debugging)
  :short "Disassemble a function"
  :long "<p>The macro @('disassemble$') provides a convenient interface to the
 underlying @('disassemble') utility of the host Common Lisp implementation,
 which prints assembly code for a given function symbol at the terminal.  If
 the argument is instead a macro alias for a function symbol (see @(see
 macro-aliases-table)), then it prints assembly code for that function symbol
 instead.</p>

 <p>@('Disassemble$') works by including the community book
 @('books/misc/disassemble.lisp'), which defines the supporting function
 @('disassemble$-fn'), and then by calling that function.  Note that the
 arguments to @('disassemble$') are evaluated.  Also note that
 @('disassemble$') is intended as a top-level utility for the ACL2 loop, not to
 be called in code; for such a purpose, include the above book and call
 @('disassemble$-fn') directly.</p>

 @({
  Example Forms:

  (disassemble$ 'foo)
  (disassemble$ 'foo :recompile t)

  General Forms:
  (disassemble$ form)
  (disassemble$ form :recompile flg)
 })

 <p>where @('form') evaluates to a function symbol or a macro alias for a
 function symbol and @('flg') evaluates to any value.  If @('flg') is @('nil'),
 then the existing definition of that function symbol is disassembled.  But if
 @('flg') is supplied and has a value other than @('nil') or @(':default'), and
 if that function symbol is defined in the ACL2 loop (not merely in raw Lisp;
 for example, see @(see set-raw-mode)), then the disassembly will be based on a
 recompilation of that ACL2 definition.  Normally this recompilation is not
 necessary, but for some host Lisps, it may be useful; in particular, for CCL
 the above book arranges that source code information is saved, so that the
 output is annotated with such information.  When recompilation takes place,
 the previous definition is restored after disassembly is complete.  Finally,
 if @('flg') is omitted or has the value @(':default') &mdash; i.e., in the
 default case &mdash; then recompilation may take place or not, depending on
 the host Lisp.  The values of @('(@ host-lisp)') for which recompilation takes
 place by default may be found by looking at the above book, or by including it
 and evaluating the constant @('*host-lisps-that-recompile-by-default*').  As
 of this writing, CCL is the only such Lisp (because that is the one for which
 we can obtain source annotation in the output by recompiling).</p>")

(defxdoc dive-into-macros-table
  :parents (proof-builder dv)
  :short "Right-associated function information for the @(see proof-builder)"
  :long "@({
  Examples:
  ACL2 !>(dive-into-macros-table (w state))
  ((CAT . EXPAND-ADDRESS-CAT)
   (LXOR . EXPAND-ADDRESS-LXOR)
 })

 <p>This table associates macro names with functions used by the interactive
 @(see proof-builder)'s @('DV') and numeric diving commands (e.g., @('3')) in
 order to dive properly into subterms.  See @(see proof-builder), in particular
 the documentation for @('DV').</p>

 <p>This table can be extended easily.  See @(see add-dive-into-macro) and also
 see @(see remove-dive-into-macro).</p>

 <p>The symbol associated with a macro should be a function symbol taking four
 arguments, in this order:</p>

 <ul>
 <li>@('car-addr')<br/>
     <blockquote>the first number in the list given to the interactive @(see
     proof-builder)'s @('DV') command</blockquote></li>
 <li>@('raw-term')<br/>
     <blockquote>the untranslated term into which we will
     dive</blockquote></li>
 <li>@('term')
     <blockquote>the translated term into which we will dive</blockquote></li>
 <li>@('wrld')
     <blockquote>the current ACL2 logical @(see world)</blockquote></li>
 </ul>

 <p>The function will normally return a list of positive integers, representing
 the (one-based) address for diving into @('term') that corresponds to the
 single-address dive into @('raw-term') by @('car-address').  However, it can
 return @('(cons str alist)'), where @('str') is a string suitable for @(tsee
 fmt) and @('args') is the corresponding alist for @(tsee fmt).</p>

 <p>Referring to the example above, @('expand-address-cat') would be such a
 function, which will be called on @('raw-term') values that are calls of
 @('cat').  See the community book @('books/misc/rtl-untranslate.lisp') for the
 definition of such a function.</p>

 <p>See @(see table) for a general discussion of tables.</p>")

(defxdoc dmr
  :parents (debugging break-rewrite accumulated-persistence)
  :short "Dynamically monitor rewrites and other prover activity"
  :long "<p>In addition to utilities that allow you to set breakpoints or print
 rewriting information to the screen &mdash; see @(see break-rewrite) (also see
 related utility @(see with-brr-data)) &mdash; ACL2 provides a utility for
 watching the activity of the rewriter and some other proof processes, in real
 time.  This utility is called ``dmr'', which is an acronym for ``dynamically
 monitor rewrites''.  The utility comes in two parts: an ACL2 component that
 frequently updates a file (the ``dmr file'') containing the relevant
 information, and an Emacs component that frequently updates an Emacs
 buffer (the ``dmr buffer'') with the contents of that file.  Other editors
 could, in principle, be programmed to display that file; anyone developing
 such a capability is invited to contribute it to the ACL2 community.</p>

 <p>The dmr utility can be extremely helpful for expensive proofs, especially
 when ACL2 is not providing any output to the terminal.  The @(see
 break-rewrite) and @(tsee accumulated-persistence) utilities may be a bit
 easier to use, so you might want to try those first.  But the dmr utility can
 be a very helpful debugging aide, as it can visually give you a sense of where
 ACL2 is spending its time.</p>

 <p>The Emacs portion of this utility is already loaded if you load the
 distributed Emacs file @('emacs-acl2.el') from a suitable directory; see @(see
 emacs).  Otherwise, load into Emacs the file @('monitor.el') from that same
 directory.  (You only need to do that once in your Emacs session.)  Then each
 time you want to observe the rewriter in action, invoke the following to see
 it displayed in a buffer, which we call the ``dmr buffer'':</p>

 @({
  Control-t 1
 })

 <p>But first you will need to enable monitoring at the ACL2 level:</p>

 @({
  (dmr-start)
 })

 <p>Monitoring has some cost.  So if you have started it, then at some point
 you may want to turn it off when not using it.  Any time the dmr buffer
 (generally called @('"acl2-dmr-<user_name>"')) is not visible, Emacs
 monitoring is turned off.  You can also turn off Emacs monitoring explicitly,
 with:</p>

 @({
  Control-t 2
 })

 <p>At the ACL2 level you can disable monitoring as follows:</p>

 @({
  (dmr-stop)
 })

 <p><i>Interpreting the dmr buffer display.</i></p>

 <p>We explain the dmr buffer display by way of the following example.  It is a
 snapshot of a dmr buffer taken from one of the community books,
 @('books/workshops/2004/legato/support/proof-by-generalization-mult.lisp').</p>

 @({
   0. (DEFTHM . WP-ZCOEF-G-MULTIPLIES)
   1. SIMPLIFY-CLAUSE
     2. Rewriting (to simplify) the atom of literal 18; argument(s) 1
     4. Rewriting (to simplify) the expansion; argument(s) 3|2
     7. Applying (:DEFINITION WP-ZCOEF-G)
  *  8. Rewriting (to simplify) the rewritten body; argument(s) 2|1|2|2
  *  13. Applying (:REWRITE MOD-ZERO . 2)
  *    14. Rewriting (to establish) the atom of hypothesis 4
  *    15. Applying (:META META-INTEGERP-CORRECT)
 })

 <p>Each line indicates an ACL2 activity that leads to the activity shown on
 the line just below it.  Moreover, lines are sometimes collapsed to make the
 display more compact.  Consider for example the first few lines.  Above, we
 are proving a theorem named @('WP-ZCOEF-G-MULTIPLIES').  Lines 1 and 2 show
 the @(see clause) simplification process invokes the rewriter on the 18th
 literal.  (Recall that a clause is a disjunction of literals; for example the
 clause @('{(NOT A), (NOT B), C}') would be displayed as @('(IMPLIES (AND A B)
 C)').)  This 18th literal mentioned on line 2 is a function call @('(f arg1
 ...)'), and ``@('argument(s) 1')'' indicates that the rewriter, which works
 inside-out, is considering the first argument (``@('arg1')'').  Thus the
 display could instead have shown the following.</p>

 @({
     2. Rewriting (to simplify) the atom of literal 18
     3. Rewriting (to simplify) the first argument
     4. Rewriting (to simplify) the expansion; argument(s) 3|2
 })

 <p>But it saved space to combine lines 2 and 3.  Line 4 suggests that the
 above @('arg1') is a function call that has been opened up because of an
 @(':expand') hint or, perhaps, an expansion directed explicitly by the prover
 (as can happen during induction).  The annotation ``@('argument(s) 3|2')''
 then indicates that the rewriter is diving into the third argument of the
 expansion, and then into the second argument of that.  Let us call the result
 @('term7') (since it is the one to be considered on line 7).</p>

 <p>Now consider the next two lines:</p>

 @({
     7. Applying (:DEFINITION WP-ZCOEF-G)
  *  8. Rewriting (to simplify) the rewritten body; argument(s) 2|1|2|2
 })

 <p>Line 7 is saying that @('term7') (defined above) is modified by applying
 the definition of @('WP-ZCOEF-G') to it.  Line 8 then says that the body of
 this definition has been rewritten (with its formals bound to the actuals from
 @('term7')) and the rewriter is diving into the subterms of that rewritten
 body, as indicated.  Notice also that line 8 is the first line marked with an
 asterisk (``@('*')'') in the margin.  This line is the first that is different
 from what was shown the previous time the display was updated (about 1/10
 second earlier, by default).  When a line is marked with an asterisk, so are
 all the lines below it; so the lines without an asterisk are those that have
 been stable since the last display.  In this example we may see line 7 marked
 without an asterisk for a while, which suggests that the rule @('(:DEFINITION
 WP-ZCOEF-G)') is expensive.  (Also see @(see accumulated-persistence).)  In
 general, a line that persists for awhile without a leading asterisk can
 suggest why the proof is taking a long time.</p>

 <p>Finally let us consider line 13 and the two lines below it.  The phrase
 @('"'Applying (:REWRITE MOD-ZERO . 2)"') says that the indicated rewrite
 rule is being considered for application to the current term.  There are very
 weak criteria for ``Applying'' to be printed: the rule must be enabled, and
 top-level function symbols much suitably match for the term and the rule.  In
 particular, the ``Applying'' line does not imply that the rule actually
 matches the term.  That said: in the case of line 13, matching clearly was
 successful, since line 14 indicates an attempt to establish the rule's fourth
 hypothesis.</p>

 <p>Finally, note the indentation of line 14 relative to line 13.  Extra
 indentation occurs when an attempt is being made to relieve a hypothesis
 (i.e., rewrite it to @('t')).  In particular, rewrites that will be
 incorporated directly into a (top-level) literal are all indented just two
 spaces, starting with the first rewrite directly under a process such as
 @('SIMPLIFY-CLAUSE') (shown line 1 above).  If the indentation is at least the
 value of raw Lisp variable @('*dmr-indent-max*') (by default, 20), then the
 indentation is restricted to that column, but ACL2 prints @('{n}') where n is
 the column that would have been used for indentation if there were no
 maximum.</p>

 <p>You can move the cursor around in the dmr buffer even while it is being
 updated.  But emacs will attempt to keep the cursor no later than the first
 asterisk (``@('*')'') in the margin.  Thus, you can move the cursor around in
 the stable part of the display, and emacs will keep the cursor in that stable
 part.</p>

 <p>WARNING: Things could go terribly wrong if the same user runs two different
 ACL2 sessions with dmr active, because the same file will be written by two
 different ACL2 processes.</p>

 <p>WARNING: For dmr to work, emacs and ACL2 need to be run on the same machine
 because the file used to communicate between ACL2 and emacs is under
 @('/tmp').  Except, you can probably hack around that restriction by changing
 @('*dmr-file-name*') in ACL2 (in raw Lisp) and correspondingly in Emacs file
 @('monitor.el').</p>

 <p>More generally, advanced users are welcome to search for the string</p>

 @({
  User-settable dmr variables
 })

 <p>in ACL2 files @('interface-raw.lisp') and @('emacs/monitor.el') in order to
 customize their dmr environments.</p>

 <p>In order to update the dmr file with the latest stack information,
 interrupt ACL2 and then evaluate: @('(dmr-flush)').  In order to support
 resumption of the interrupted proof (assuming your host Common Lisp supports
 resumption), evaluation of @('(dmr-start)') will automatically enable the
 debugger if it is not already enabled and not fully disabled with value
 @(':never') (see @(see set-debugger-enable)).  If such automatic enabling
 takes place, then @('(dmr-stop)') will restore the old setting of the debugger
 unless, after @('(dmr-start)') enables the debugger but before @('(dmr-stop)')
 is called, you call @(tsee set-debugger-enable) (or more precisely: function
 @('set-debugger-enable-fn') is called).</p>

 <p>Note for users of the experimental extension ACL2(p) (see @(see
 parallelism)): when waterfall-parallelism has been set to a non-@('nil') value
 (see @(see set-waterfall-parallelism)), statistics about parallel execution
 are printed instead of the usual information.</p>")

(defxdoc do$
  :parents (loop$ do-loop$)
  :short "Definition of @('do$')"
  :long "<p>@('Do$') is the logical function that interprets @('do')
  @('loop$')s.  See @(see do-loop$) for a discussion of @('do$').</p>

  <p>The function takes six arguments but only the first five are
  relevant to its logical value.</p>

  <ul>

  <li>@('measure-fn') &mdash; a @(tsee lambda) object that computes the measure
  that supposedly decreases (under @(tsee l<)) on each iteration of the
  @('do-fn') and is checked after each iteration, </li>

  <li>@('alist') &mdash; an alist that binds the variable symbols used in the
  body and @('finally') clause (if any) to their values,</li>

  <li>@('do-fn') &mdash; a @('lambda') object that computes the results of one
  iteration, where the results are represented by a triple consisting of an
  exit token that indicates where control goes next, the value (if a
  @('return') was executed), and a new @('alist'),</li>

  <li>@('finally-fn')&mdash; a @('lambda') object that computes the value of
  the @('finally') clause, and</li>

  <li>@('values') &mdash; the output signature of the value to be returned if
  the @('measure') fails to decrease.</li>

  </ul>

  @(def do$)

  <p>The last argument is only relevant in the error message printed if the
  @('do$') fails to terminate and that message is not part of the returned
  value.</p>")

(defxdoc do-loop$
  :parents (loop$)
  :short "Iteration with @(tsee loop$) using local variables and @(see stobj)s"
  :long "<p>This topic assumes that you have read the introduction to
 @('loop$') expressions in ACL2; see @(see loop$).  Here we give more complete
 documentation on @('DO') @('loop$') expressions.  This discussion is
 partitioned into the following sections</p>

 <ul>
 <li>INFORMAL INTRODUCTION &mdash; examples of @('DO') @('loop$') expressions</li>
 <li>SYNTAX &mdash; detailed discussion of the legal syntax</li>
 <li>SEMANTICS &mdash; detailed discussion of how @('DO') @('loop$') expressions
 are translated into calls of the general-purpose function @(tsee DO$)</li>
 <li>SIGNALING ERRORS &mdash; how @('DO') @('loop$')s can signal errors</li>
 </ul>

 <p>For a discussion of proofs about @('loop$')s, see @(see
 stating-and-proving-lemmas-about-loop$s).</p>

 <p>More examples of @(tsee loop$) expressions, including @('DO') @('loop$')s,
 may be found in @(see community-book) @('projects/apply/loop-tests.lisp').</p>

 <h3>INFORMAL INTRODUCTION</h3>

 <p>The most basic @('DO') @('loop$') expressions have the following form.</p>

 @({
 (loop$ WITH v1 = a1
        ...
        WITH vn = an
        DO body)
 })

 <p><b>A Basic Example</b></p>

 <p>The example @('loop$') expression below initially stores the list @('(a b
 c)') in the variable @('x') and @('nil') in the variable @('y').  Then it
 iterates, repeatedly popping the first element of @('x') onto @('y') until
 @('x') is empty.  Then it returns the final value of @('y').</p>

 @({
 ACL2 !>(loop$ with x = '(a b c)
               with y = nil
               do (cond ((consp x)
                         (progn (setq y (cons (car x) y))
                                (setq x (cdr x))))
                        (t (return y))))
 (C B A)
 ACL2 !>
 })

 <p>This example illustrates the basic operation of @('DO') @('loop$')
 expressions.</p>

 <ul>

 <li>Initially, variables are initialized according to the @('WITH')
 clauses: for each binding @('WITH Vi = Ei'), we say that @('Vi') is a
 <i>@('WITH')-bound variable</i>, and @('Vi') is initially bound to the value
 of @('Ei').

 <ul><li>In this example, @('x') is initially bound to the list @('(a b c)')
 and @('y') is initially bound to @('nil').</li></ul></li>

 <li>Then, the <i>loop body</i> &mdash; i.e., the term after the @('DO')
 keyword &mdash; is repeatedly evaluated.  An update to @('WITH')-bound
 variable @('Vj') occurs whenever an expression @('(setq Vj Ej)') is
 encountered while evaluating the loop body, binding @('Vj') to the value of
 @('Ej') (which may reference the current values of @('WITH')-bound variables).

 <ul><li>In this example, as long is @('x') is a cons, @('y') is assigned to
 @('(cons (car x) y)') and then @('x') is assigned to the @('cdr') of its
 current value.</li></ul></li>

 <li>Ultimately an expression @('(RETURN E)') should be encountered, in which
 case the value of @('E') is returned &mdash; where as before, @('E') may
 reference the current values of @('WITH')-bound variables.

 <ul><li>In this example, when @('x') is not a cons (and hence is, in fact,
 @('nil')), the current value of @('y') is returned as the value of the
 @('loop$') expression.  By this point each element of the initial value of
 @('x') has been pushed onto @('y'), so the value @('(c b a)') is
 returned.</li></ul></li>

 </ul>

 <p>Note that @('progn') is permitted as shown, to connect a sequence of
 expressions.  Indeed, that is how more than one assignment is accomplished;
 unlike Common Lisp, the @('DO') keyword is followed by exactly one expression,
 so @('DO expr1 expr2') is illegal in ACL2 but @('DO (progn expr1 expr2)') is
 fine.</p>

 <p>Also note that the @('WITH')-bound variables are initialized sequentially:
 later bindings may reference values of earlier ones, for example as
 follows.</p>

 @({
 ACL2 !>(loop$ with x = (* 3 4) with y = (* 10 x) do (return (list y)))
 (120)
 ACL2 !>
 })

 <p>See @(see lp-section-14) of the @('Loop$') Primer for some exercises in
 writing and executing @('DO') @('loop$')s (with answers in a Community Book).
 But remember to come back here when you get to the end of that section.</p>

 <p><b>Parallel Assignment Using @('Mv-setq')</b></p>

 <p>ACL2 also supports parallel assignment to two or more variables, using
 @('mv-setq').  The following is equivalent to the example immediately
 above.</p>

 @({
 ACL2 !>(loop$ with x = '(a b c)
                with y = nil
                do (cond ((consp x)
                          (mv-setq (x y)
                                   (mv (cdr x) (cons (car x) y))))
                         (t (return y))))
 (C B A)
 ACL2 !>
 })

 <p>Thus, the first argument of an @('mv-setq') call is not evaluated, and is a
 list of distinct variables of length at least 2.  The second argument is any
 expression that returns multiple values consistent with the first argument
 &mdash; ``consistent'' in the sense that the number of values returned equals
 the number of variables in the first argument and stobjs must match up.  Thus,
 the rules for @('(mv-setq vars expr)') are the same as for @('(mv-let vars
 expr ...)').</p>

 <p><b>The @('FINALLY') Clause</b></p>

 <p>We have seen the @('loop$') keywords @('WITH') and @('DO').  A third
 @('loop$') keyword, @('FINALLY'), is also supported.  Here is a variant of the
 preceding example that illustrates the use of @('FINALLY').  The iteration
 stops with the @('(loop-finish)') form this time, rather than with a call of
 @('return').  Execution of @('(loop-finish)') passes control to the
 @('FINALLY') clause, which is executed just like the @('DO') body but with a
 single pass, thus determining the value of the @('loop$') &mdash; in this
 example, returning the final value of @('y').</p>

 @({
 ACL2 !>(loop$ with x = '(a b c)
               with y = nil
               do (cond ((consp x)
                         (progn (setq y (cons (car x) y))
                                (setq x (cdr x))))
                        (t (loop-finish)))
               finally (return y))
 (C B A)
 ACL2 !>
 })

 <p>This example illustrates that @('(loop-finish)') terminates the iteration,
 passing control to the @('FINALLY') clause if there is one.  The @('FINALLY')
 clause is evaluated under the current bindings of the @('WITH')-bound
 variables, just as a @('DO') body is executed (but with a single pass rather
 than iteration).</p>

 <p>The value returned by a @('DO') @('loop$') expression is @('nil') when no
 @('return') expression is evaluated (or more generally, a suitable value
 consistent with the @(':VALUES') keyword discussed below).  Here is an
 example, which illustrates an error that may be easy to commit.</p>

 @({
 ACL2 !>(loop$ with x = '(a b c)
               with y = nil
               do (cond ((consp x)
                         (progn (setq y (cons (car x) y))
                                (setq x (cdr x))))
                        (t (loop-finish)))
               finally (length y))
 NIL
 ACL2 !>
 })

 <p>Presumably the intention was to return the length of @('y'), which in this
 case would be 3.  But then the @('FINALLY') clause should have been
 @('(return (length y))').</p>

 <p><b>The @(':VALUES') Keyword</b></p>

 <p>The @(':VALUES') keyword is necessary for a @('loop$') expression that
 returns a @(see double-float), a @(see stobj) or @(see multiple-value)s.  When
 the @(':VALUES') keyword is used, the syntax is @(':VALUES (v0 ... vk)'),
 where each @('vi') is either @('nil'), @(':df'), or a stobj
 name. @(':VALUES (nil)') denotes return of a single ordinary value;
 @(':VALUES (s)') denotes return of a single value that is a stobj named
 @('s'); and @(':VALUES (v0 ... vk)') for k &gt; 0 denotes return of k+1
 values, where @('vi') is @('nil') if the ith returned value is an ordinary
 value, @(':DF') if the ith returned value is a double-float, and otherwise
 @('vi') is the name of the stobj returned as the ith value.  You may
 recognize (v0 ... vk) as an output signature.  If the measure supplied to
 @('do$') fails to decrease on an iteration, an error is caused and the output
 signature is used compute a ``default value,'' which is generally a list of
 k+1 objects (but is a single object when k is 0).  The ith object in the
 default value is @('nil') if @('vi') is @('nil'), is @('#d0.0') if @('vi') is
 @(':DF'), and is the last latched value of the named stobj otherwise. No stobj
 name may be duplicated, and @(':VALUES') must appear between the @('DO') loop
 keyword and the @('DO') body.  Let's look at an example.</p>

 <p>Below we introduce a @(see stobj) and add a @(see warrant) for its accessor
 and updater.  Warrants are necessary for functions called in @('DO') bodies
 and @('FINALLY') clauses in order for those forms to be evaluated.  See @(see
 loop$) for a discussion of the necessity of such warrants.  The two @('loop$')
 expressions are similar in nature to those above, first without and then with
 a @('FINALLY') clause; also see the discussion below.  All forms below
 complete successfully.</p>

 @({
 (include-book "projects/apply/top" :dir :system)
 (defstobj st fld)
 (defwarrant fld)
 (defwarrant update-fld)
 ; Check that (fld st) is currently nil.
 (assert-event (equal (fld st) nil))
 (loop$ with x = '(1 2 3)
        do
        :values (st)
        (cond ((endp x)
               (return st))
              (t (mv-setq (st x)
                          (let ((st (update-fld (cons (car x)
                                                      (fld st))
                                                st)))
                            (mv st (cdr x)))))))
 (assert-event (equal (fld st) '(3 2 1)))
 (update-fld nil st)
 (assert-event (equal (fld st) nil))
 (loop$ with x = '(1 2 3)
        do
        :values (st)
        (cond ((endp x)
               (loop-finish))
              (t (progn (setq st
                              (update-fld (cons (car x)
                                                (fld st))
                                          st))
                        (setq x (cdr x)))))
        finally (return st))
 (assert-event (equal (fld st) '(3 2 1)))
 })

 <p>These loops are similar to those we saw earlier, but this time, when we pop
 values from @('x') they go into a stobj.  Since we return that stobj, @('st'),
 the @(':VALUES') is @('(st)').  The fifth argument of the call of @('do$')
 generated from these @('loop$')s is @(''(st)').  One might expect @(':VALUES')
 to be @('st') instead, but @(':VALUES') is always a list; when a single value
 is returned, @(':VALUES') is a one-element list.  Thus, the default for
 @(':VALUES') is @('(nil)').</p>

 <p>Notice that the examples above apply @('setq') to @('st').  This
 illustrates that a variable assigned by @('setq') or @('mv-setq') must either
 be declared in a @('WITH') clause or be a known stobj.  Of course, here
 @('st') is a known stobj.  In fact, stobjs are not allowed to be declared in
 @('WITH') clauses (and that is not necessary for assigning to them).</p>

 <p>Note that it is possible to write @('DO') loops without any @('WITH')
 clauses, provided a stobj is being manipulated and measured in the body.  For
 example, using the stobj declared in the previous example,</p>

 @({
 (loop$ do
        :values (st)
        :measure (acl2-count (fld st))
        (if (endp (fld st))
            (return st)
            (if (equal 3 (car (fld st)))
                (return st)
                (setq st (update-fld (cdr (fld st)) st)))))
 })

 <p>is acceptable.  In Common Lisp, @('(loop$ do <body>)') loops until a
 @('return') is executed and so to be admissible in ACL2 some @(':measure')
 must be specified (unless there is @('return') on every branch through
 @('<body>')).  If there are no @('WITH') clauses, stobjs are the only objects
 that might be measured to explain termination, and ACL2 cannot guess effective
 measures of stobjs.</p>

 <p>To see some advice about proving inductive theorems about @('DO') loops
 measured by stobjs, see @(see stating-and-proving-lemmas-about-loop$s).</p>

 <p><b>The @('OF-TYPE') Keyword</b></p>

 <p>So far our examples have all involved @('loop$') expressions that are
 evaluated directed at the ACL2 prompt.  These do not require the @('OF-TYPE')
 keyword described in this section.  But @('loop$') expressions may also appear
 in definitions.  When these definitions are to be @(see guard)-verified,
 @('OF-TYPE') keyword may be critical.</p>

 <p>Consider the following example, which searches for an even number in a
 given list of integers, returning @('t') if one is found and else @('nil').
 As usual, we start by including the usual book for reasoning about
 @('loop$').</p>

 @({
 (include-book "projects/apply/top" :dir :system)
 (defun has-evenp (x)
   (declare (xargs :guard (integer-listp x)))
   (loop$ with temp of-type (satisfies integer-listp) = x
          do
          (cond ((endp temp)
                 (return nil))
                ((evenp (car temp))
                 (return t))
                (t
                 (setq temp (cdr temp))))))
 })

 <p>We see that the expression immediately following @('OF-TYPE') is a legal
 @(see type-spec), in this case expressing that @('(integer-listp temp)') holds
 for every value of @('temp') during execution of the @('loop$').  Let's see
 why this use of @('OF-TYPE') is necessary.  When it is omitted, guard
 verification fails with the following top-level checkpoints.</p>

 @({
 Subgoal 1.2
 (IMPLIES (AND (ALISTP ALIST)
               (NOT (CONSP (CDR (ASSOC-EQ-SAFE 'TEMP ALIST)))))
          (NOT (CDR (ASSOC-EQ-SAFE 'TEMP ALIST))))

 Subgoal 1.1
 (IMPLIES (AND (ALISTP ALIST)
               (CONSP (CDR (ASSOC-EQ-SAFE 'TEMP ALIST))))
          (INTEGERP (CADR (ASSOC-EQ-SAFE 'TEMP ALIST))))
 })

 <p>To understand these checkpoints we need to understand a bit about how ACL2
 gives a semantics to @('DO') @('loop$') expressions (as we explain in more
 detail in the section on Semantics below).  In the ACL2 logic, a @('DO')
 @('loop$') expression is represented as a transformation on an association
 list, named @('alist'), that assigns values to every variable in the
 expression.  This alist is transformed by each iteration through the loop.</p>

 <p>The value of the variable @('temp') in @('alist') is @('(assoc-eq-safe
 'temp alist)'), where @('assoc-eq-safe') is just a variant of @(tsee assoc)
 whose guard makes no requirements on the alist.  The first checkpoint
 above (Subgoal 1.2) thus says that if the value of @('temp') is not a cons,
 then it's @('nil').  That requirement comes from the expression, @('(endp
 temp)'), since the guard of @(tsee endp) is that its argument is a cons or
 @('nil').  The second checkpoint (Subgoal 1.1) says that if the value of
 @('temp') is a cons, then its @('car') is an integer.  That requirement comes
 from the expression @('(evenp (car temp))'), since the guard for @(tsee evenp)
 requires its argument to be an integer.</p>

 <p>When we add the restriction provided by the @('OF-TYPE') keyword that
 @('temp') satisfies @(tsee integer-listp), the checkpoints each get the added
 hypothesis @('(integer-listp (cdr (assoc-eq-safe 'temp alist)))').  That
 allows the guard proof to go through.  This addition also imposes that same
 requirement on the initial alist, but it is discharged because the guard for
 @('has-evenp') specifies @('(integer-listp x)') and @('temp') is initially
 assigned to @('x').  Importantly, use of the @('OF-TYPE') keyword on a
 variable imposes a guard proof obligation for every assignment to that
 variable, that the new value of that variable also satisfies the given type.
 In this case, this means that under the hypotheses that @('(endp temp)') and
 @('(evenp (car temp))') are false, and also assuming that @('temp') satisfies
 @('integer-listp') &mdash; where here, @('temp') is @('(cdr (assoc-eq-safe
 'temp alist))') &mdash; then @('(cdr temp')) satisfies @('integer-listp').
 ACL2 discharges this requirement automatically.</p>

 <p><b>The @(':GUARD') Keyword</b></p>

 <p>Consider the following definition, which is identical to the one for
 @('has-evenp') displayed above except that instead of using the @('OF-TYPE')
 keyword, it uses the @(':GUARD') keyword.</p>

 @({
 (defun has-evenp (x)
   (declare (xargs :guard (integer-listp x)))
   (loop$ with temp = x
          do
          :guard (integer-listp temp)
          (cond ((endp temp)
                 (return nil))
                ((evenp (car temp))
                 (return t))
                (t
                 (setq temp (cdr temp))))))
 })

 <p>This definition is accepted by ACL2 for much the same reason that the
 preceding one was accepted.  The difference is that while the @('OF-TYPE')
 keyword adds a requirement at every assignment of the variable, the
 @(':GUARD') imposes the invariant that when the guard holds entering the
 @('loop$') body, it also holds when the @('loop$') body is next entered.  Thus
 we see the following in the @('Goal') generated for the guard conjecture,
 where @('new-alist') is let-bound (not shown here) to the result of updating
 @('alist') after one iteration through the loop, and where @('(equal exit-flg
 nil)') indicates that another iteration is pending (because neither a
 @('return') nor a @('loop-finish') was executed).</p>

 @({
 (IMPLIES (AND (AND (ALISTP ALIST)
                    (INTEGER-LISTP (CDR (ASSOC-EQ-SAFE 'TEMP ALIST))))
               (EQUAL EXIT-FLG NIL))
          (AND (ALISTP NEW-ALIST)
               (INTEGER-LISTP (CDR (ASSOC-EQ-SAFE 'TEMP NEW-ALIST)))))
 })

 <p>The @(':guard') is generally ignored when it is within the definition's
 body for a guard-verified or a @(':')@(tsee program)-mode function.  The
 reason is that in these cases, the @('loop$') expression is converted to a
 Common Lisp @('loop') expression.  (There are exceptions involving @(tsee
 set-guard-checking) and @(see invariant-risk).)  However, in other cases the
 @(':guard') is checked at runtime.  Consider the following example.</p>

 @({
 (defun f (lst)
   (loop$ with x = lst
          do
          :guard (consp x)
          (cond ((consp x)
                 (setq x (cdr x)))
                (t (return x)))))
 })

 <p>Here we see a runtime guard violation.</p>

 @({
 ACL2 !>(f '(a b c d))


 ACL2 Error [Evaluation] in TOP-LEVEL:  The guard for a DO$ form,
 (AND (ALISTP ALIST) (CONSP (CDR (ASSOC-EQ-SAFE 'X ALIST)))),
  has been violated by the following alist:
 ((X)).
 See :DOC do-loop$.

 ACL2 !>
 })

 <p>As noted in the preceding section (on &ldquo;The @('OF-TYPE')
 Keyword&rdquo;), a call of @('do$') transforms an alist with each iteration
 through the loop.  The alist initially binds the symbol @('X') to the list
 @('(A B C D)'), and each iteration modifies that binding by @('cdr')ing the
 value of @('X'), until finally that value is @('nil') &mdash; and then a guard
 check fails for the value of @('X'), i.e., @('(CONSP (CDR (ASSOC-EQ-SAFE 'X
 ALIST)))') is @('nil').</p>

 <p>A more detailed explanation may be found in the final section,
 &ldquo;Semantics&rdquo;.</p>

 <p><b>The @(':MEASURE') Keyword</b></p>

 <p>The discussion above doesn't address the obvious possibility that a @('DO')
 @('loop$') may not terminate.  Consider the following example, which not only
 assumes that the usual book has been included as discussed above, but also
 assumes that the form @('(defwarrant princ$)') has been evaluated.</p>

 @({
 ACL2 !>(loop$ with x = '(100 200 300)
               do
               :values (state)
               (setq state (princ$ (car x) *standard-co* state)))


 ACL2 Error in TOP-LEVEL:  No :MEASURE was provided after the DO operator
 and we failed to find a likely measure.  Please supply a :MEASURE in
 (LOOP$ WITH X = '(100 200 300)
        DO :VALUES (STATE)
        (SETQ STATE
              (PRINC$ (CAR X) *STANDARD-CO* STATE))).
 See :DOC loop$.

 ACL2 !>
 })

 <p>As suggested by the error message, ACL2 has tried to guess a measure, i.e.,
 a term whose value is expected to decrease on each successive iteration.  This
 notion of ``decrease'' is the expected one when the value of the measure is a
 natural number: smaller in the sense of @('<').  In general, the measure
 decreases in the sense of @('L<') when @('lex-fix') is applied to each
 argument; see @(csee L<).</p>

 <p>Of course, no measure decreases in the example above, because the values of
 the variables don't change with each iteration.  We can see what happens when
 we supply an explicit measure: the body is evaluated, as evidenced by the
 appearance of @('100') in the output, but then the measure is evaluated and is
 seen not to have decreased from what it was at the start of the previous
 iteration.</p>

 @({
 ACL2 !>(loop$ with x = '(100 200 300)
               do
               :values (state)
               :measure (acl2-count x)
               (setq state (princ$ (car x) *standard-co* state)))
 100

 HARD ACL2 ERROR in DO$:  The measure, (ACL2-COUNT X), used in the do
 loop$ statement
 (LOOP$ WITH X = '(100 200 300)
        DO :VALUES (STATE)
        :MEASURE (ACL2-COUNT X)
        (SETQ STATE
              (PRINC$ (CAR X) *STANDARD-CO* STATE)))

 failed to decrease!  Recall that do$ tracks the values of do loop$
 variables in an alist.  The measure is computed using the values in
 the alist from before and after execution of the body.  We cannot print
 the values of double floats and live stobjs, if any are found in the
 alist, because they are raw Lisp objects, not ACL2 objects.  We print
 any double float as its corresponding rational and simply print the
 name of any live stobj (as a string).

 Before execution of the do body the alist was
 ((X 100 200 300) (STATE . "<state>")).
 After the execution of the do body the alist was
 ((X 100 200 300) (STATE . "<state>")).
 Before the execution of the body the measure was
 603.
 After the execution of the body the measure was
 603.

 Logically, in this situation the do$ returns the value of a term whose
 output signature is (STATE), where the value of any component of type
 :df is #d0.0 and the value of any stobj component is the last latched
 value of that stobj.

 ACL2 Error [Evaluation] in TOP-LEVEL: Evaluation aborted.  To debug
 see :DOC print- gv, see :DOC trace, and see :DOC wet.

 ACL2 !>
 })

 <p>Presumably the following is what was intended.</p>

 @({
 ACL2 !>(loop$ with x = '(100 200 300)
               do
               :values (state)
               :measure (acl2-count x)
               (if (atom x)
                   (return state)
                 (progn
                   (setq state (princ$ (car x) *standard-co* state))
                   (setq x (cdr x)))))
 100200300<state>
 ACL2 !>
 })

 <p>In fact, the @(':MEASURE') can be omitted in this case; ACL2 is able to
 guess @('(ACL2-COUNT X)').</p>

 <p>@(csee Guard) verification requires a proof that the measure does indeed go
 down in the sense of @('L<'), after applying @('lex-fix') to the arguments;
 see @(csee L<).  Fortunately, guard verification takes advantage of
 information specified by @('OF-TYPE') and @(':GUARD') keywords.  For example,
 the following two definitions are admitted (after the usual initial
 @('include-book') form), even though termination would not be provable without
 the @('OF-TYPE') expression in the first and the DO body's @(':GUARD') in the
 second; consider the case that @('n') is -1.</p>

 @({
 (defun foo (max)
   (declare (xargs :guard (natp max)))
   (loop$ with n of-type (satisfies natp) = max
          do
          (if (= n 0)
              (return 'stop)
            (setq n (- n 1)))))

 (defun foo (max)
   (declare (xargs :guard (natp max)))
   (loop$ with n = max
          do
          :guard (natp n)
          (if (= n 0)
              (return 'stop)
            (setq n (- n 1)))))
 })

 <p><b>A More Complex Example</b></p>

 <p>We conclude with an example presented in the documentation for @(tsee
 loop$) that illustrates all the features above.  Notice that the @(':GUARD')
 keyword may appear not only in the @('DO') body but also in the @('FINALLY')
 clause, to specify that the indicated guard holds upon entry to the
 @('FINALLY') clause.  Here we assume that we have already evaluated not only
 the usual @('include-book') form, but also the @('defstobj') and
 @('defwarrant') forms above.</p>

 @({
 (defun test-loop$ (i0 max st)
   (declare (xargs :guard (and (natp i0) (natp max))
                   :stobjs st))
   (loop$ with i of-type (satisfies natp) = i0
          with cnt of-type integer = 0
          do
          :measure (nfix (- max i))
          :guard (and (natp max)
                      (natp cnt)
                      (stp st))
          :values (nil st) ; shape of return; can be omitted when it's (nil)
          (if (>= i max)
              (loop-finish)
            (progn (setq st (update-fld i st))
                   (mv-setq (cnt i)
                            (mv (+ 1 cnt) (+ 1 i)))))
          finally
          :guard (stp st)
          (return
           (mv (list 'from i0 'to max 'is cnt 'steps 'and 'fld '= (fld st))
               st))))
 })

 <p>Notice that any variables bound above the @('loop$') may appear in it, for
 example, the formal parameters of this function.  But only variables that are
 @('WITH')-bound or declared as @(see stobj)s may be assigned with @('setq') or
 @('mv-setq').  The @(':GUARD') of @('(stp st)') is necessary, because ACL2
 does not automatically infer that stobj recognizer calls hold inside
 @('loop$') expressions the way it does in ordinary bodies of @(tsee defun)
 forms.</p>

 <p>We can evaluate the function above, as in the following example.</p>

 @({
 ACL2 !>(test-loop$ 3 8 st)
 ((FROM 3 TO 8 IS 5 STEPS AND FLD = 7)
  <st>)
 ACL2 !>
 })

 <h3>SYNTAX</h3>

 @({
 General Form:

 (LOOP$ WITH var1 OF-TYPE spec1 = init1 ; a WITH declaration
        WITH var2 OF-TYPE spec2 = init2
        ...
        DO
        :measure m
        :guard do-guard
        :values v
        do-body
        FINALLY
        :guard fin-guard
        fin-body)
 })

 <p>where much of that is optional: ``@('OF-TYPE speci')'', ``@('=
 initi')'' (when ``@('OF-TYPE speci')'' is present), ``@(':MEASURE m')'', the
 two ``@(':GUARD') ...'' clauses, ``@(':VALUES v')'', and ``@('FINALLY
 fin-body')''.  If the @(':MEASURE') is omitted, ACL2 tries to guess a likely
 measure using the same heuristic it does with recursive @(tsee defun)s.  If
 @(':VALUES') is omitted then @('v') defaults to @('(nil)'); it indicates the
 shape of the return value for the @('loop$') expression.</p>

 <p>@('Do-body') must be a cons, not an atom, as must each of the following
 that is supplied: @('m'), @('do-guard'), @('v'), @('fin-guard'), and
 @('fin-body').</p>

 <p>All ACL2 function symbols in the measure @('m') and the two bodies must be
 @(see badge)d so @(tsee apply$) can handle them.  Furthermore, they must be
 @(see warrant)ed if proofs are to be done about them or if they are in @(see
 logic) mode and are called during evaluation.</p>

 <p>The @('do-body') and @('fin-body') positions are to be what we call
 ``DO-body term''.  <b>These are not, in general, normal ACL2 terms!  They
 allow restricted uses of @('RETURN'), @('PROGN'), @('SETQ'), @('MV-SETQ'), and
 @('LOOP-FINISH') as described below.</b> In the descriptions below we ignore
 the distinctions between translated and untranslated terms; see @(see term)).
 As usual, the restrictions on return values apply only to code, not to terms
 occurring in theorem statements.</p>

 <ul>

 <li>Every ordinary term that returns a single, non-stobj value</li>

 <li>An @('IF') call whose first argument is an ordinary term (which
 necessarily returns a single, non-stobj value) and whose true and false
 branches are DO-body terms</li>

 <li>A @('LET'), @('LET*'), or @('MV-LET') expression, subject to the following
 restrictions (unless the term is an ordinary term).

 <ul>

 <li>The terms in the bindings are all ordinary terms.</li>

 <li>The body is a DO-body term.</li>

 <li>No variable bound in the bindings is @('WITH')-bound, a known @(see
 stobj), or a variable occurring free in the surrounding DO loop$
 expression.</li>

 </ul></li>

 <li>@('(PROGN term1 term2 ... termk)'), where each @('termi') is a DO-body
 term; also @('(PROG2 term1 term2)') in that case</li>

 <li>@('(RETURN term)'), where @('term') is an ordinary term</li>

 <li>@('(LOOP-FINISH)'), but only in a DO body, not in a @('FINALLY')
 clause</li>

 <li>@('(SETQ var term)'), where the variable @('var') is declared in a
 @('WITH') declaration or is a stobj name, and @('term') is an ordinary term
 that returns a single value, that value being a stobj of type @('var') if
 @('var') is a stobj</li>

 <li>@('(MV-SETQ (var0 ... varn) term)') for two or more distinct variables
 @('vari'), where each @('vari') is declared in a @('WITH') clause or is a
 stobj name, and @('term') is an ordinary term that returns n+1 values, where
 if @('vari') is a stobj then the ith value returned is of that type</li>

 </ul>

 <p>Notice that in code, where restrictions on return values are in force, no
 stobj may be let-bound in a @('DO') body or @('FINALLY') clause.  This is due
 not only to the explicit restriction above for @('LET'), @('LET*'), and
 @('MV-LET') expressions, but also due to the first condition above, on
 ordinary terms returning a single, non-stobj value.</p>

 <p>We conclude this section by discussing some syntactic restrictions.</p>

 <p>The following restriction applies to @('loop$') expressions meeting the
 following two conditions: @(':VALUES') specifies something other than the
 default of @('(NIL)'), and there is at least one @('loop-finish') expression
 in the @('loop$') body.  In that case, there must be a @('FINALLY') clause
 that ACL2 recognizes as always executing a @('return') call.  This makes
 sense, since in Common Lisp, the value returned by a @('loop') is @('nil')
 when ``falling through'' without executing a @('return'); but @('nil') would
 violate the specified @(':VALUES') in the case above.</p>

 <p>As noted above, assignments with @('setq') and @('mv-setq') may only set
 stobj variables and variables declared using @('WITH').  This restriction
 applies to the innermost @('loop$') that contains the assignment.  The
 following, for example, is illegal because the @('WITH') clause for
 @('x') is not in the @('loop$') immediately above the assignment to @('x')
 with @('setq').</p>

 @({
 (defun do-loop-nested-outer-with-var-bad (lst)
   (loop$ with x = lst
          do
          (return
           (loop$ with temp = '(1 2 3)
                  do
                  (cond ((endp temp)
                         (return (pairlis$ x x)))
                        (t (progn (setq x (cons (car temp) x))
                                  (setq temp (cdr temp)))))))))
 })

 <p>However, we expect it to be easy in general to work around this
 restriction.  The following definition, for example, accomplishes what was
 presumably intended above and is accepted by ACL2.</p>

 @({
 (defun do-loop-nested-outer-with-var (lst)
   (loop$ with x = lst
          do
          (return
           (loop$ with temp = '(1 2 3)
                  with x = x
                  do
                  (cond ((endp temp)
                         (return (pairlis$ x x)))
                        (t (progn (setq x (cons (car temp) x))
                                  (setq temp (cdr temp)))))))))
 })

 <p>Every @('return') expression in the DO body and (if present) @('FINALLY')
 clause must return a value or @(see multiple-value)s consistent with what is
 specified by the @(':VALUES') keyword (by default, a single ordinary value).
 Note that this requirement does not tolerate the replacement of a stobj by a
 stobj that is congruent to it.</p>

 <p>It is illegal for a @('loop$') expression to be in the scope of function
 bindings of an @(tsee flet) or @(tsee macrolet) expression.</p>

 <p>As noted above, the measure, body, and @('FINALLY') clauses of a DO
 @('loop$') must be fully @(see badge)d.</p>

 <p>In a function call, it is illegal for a LOOP$ expression to occur in a slot
 whose @(see ilk) is not @('nil').</p>

 <p>See the section SIGNALING ERRORS, below, for how the syntax described here
 allows for @('DO') @('loop$')s to manipulate @(tsee stobj)s and @(tsee state),
 including how to signal errors from within the body of the @('loop$').</p>

 <h3>SEMANTICS</h3>

 <p>Consider again the initial example in the Informal Introduction above.</p>

 @({
 ACL2 !>(loop$ with x = '(a b c)
               with y = nil
               do (cond ((consp x)
                         (progn (setq y (cons (car x) y))
                                (setq x (cdr x))))
                        (t (return y))))
 (C B A)
 ACL2 !>
 })

 <p>We have seen that after initializing variables using @('WITH') clauses,
 each iteration of a @('DO') @('loop$') updates those variables by evaluating
 the body of the loop (i.e., the term after the @('DO') keyword), until a
 @('return') expression is executed to return the current value of a term
 &mdash; in this case, the current value of the term, @('y').</p>

 <p>Of course, @('progn') and @('return') are not ACL2 functions!  (Recall that
 the word ``applicative'' is part of what ``ACL2'' abbreviates.)  The following
 term is essentially what is produced from the @('loop$') expression above.  We
 discuss it below.</p>

 @({
 (DO$ ; Measure Function
      (LAMBDA$ (ALIST)
               (LET ((X (CDR (ASSOC-EQ-SAFE 'X ALIST)))
                     (Y (CDR (ASSOC-EQ-SAFE 'Y ALIST))))
                    (ACL2-COUNT X)))
      ; Initial Alist
      (LIST (CONS 'X '(A B C))
            (CONS 'Y NIL))
      ; Body Function
      (LAMBDA$ (ALIST)
               (LET ((X (CDR (ASSOC-EQ-SAFE 'X ALIST)))
                     (Y (CDR (ASSOC-EQ-SAFE 'Y ALIST))))
                    (IF (CONSP X)
                        (LIST NIL
                              NIL ; irrelevant
                              (LIST (CONS 'X (CDR X))
                                    (LIST* 'Y (CAR X) Y)))
                        (LIST :RETURN
                              Y
                              (LIST (CONS 'X X) (CONS 'Y Y))))))
      ... ; Other arguments are omitted here.
 )
 })

 <p>The display above is approximate; in particular, it hides some logically
 irrelevant clutter such as @(tsee declare) forms and it shows only arguments
 of @('do$') relevant to our discussion of the example above.  Also, the
 display employs user-level syntax (i.e., an <i>untranslated term</i>; see
 @(see term)).  See also the subsection of @(tsee lambda$) entitled ``About
 @('Lambda$')s and Prover Output.''</p>

 <p>The definition of @('do$') is given later in this topic, for those who care
 to explore it, but this discussion is intended to be self-contained.  @('Do$')
 operates by maintaining an alist that maps variables to values, for all
 variables referenced in the @('loop$') expression &mdash; though only
 variables that are declared in @('WITH') clauses or are stobjs may be
 modified.  This alist is updated on each iteration by calling @(tsee apply$)
 on the ``Body Function'' above, producing a 3-element list @('(exit-token val
 new-alist)').  If @('exit-token') is @(':RETURN') then @('val') is returned.
 But if @('exit-token') is @('nil'), then @('do$') is called recursively with
 @('new-alist') as its alist argument.</p>

 <p>To see @('do$') in action one can submit the following forms.  Here the
 body of @('f') is just the @('loop$') expression shown above.  Notice that
 @('f') is not @(see guard)-verified; after submitting @('(verify-guards f)')
 the @('loop$') expression is evaluated as a Common Lisp @('loop') call rather
 than using @('do$'), so there would be no @(see trace) output.  Don't worry
 about having a precise understanding of the fancy calls of @(tsee trace!); the
 comments there should suffice.</p>

 @({
 (include-book "projects/apply/top" :dir :system)
 (defun f ()
   (loop$ with x = '(a b c)
          with y = nil
          do (cond ((consp x)
                    (progn (setq y (cons (car x) y))
                           (setq x (cdr x))))
                   (t (return y)))))
 ; Store the translated body function so that we can access it later
 ; with (@ my-body-fn):
 (trace! (do$ :entry (f-put-global 'my-body-fn (nth 2 arglist) state)))
 ; Run f to store to my-body-fn as commented above.
 (f)
 ; Trace do$ calls and trace calls of apply$ on the body function.
 (trace! (do$ :notinline t ; include recursive calls
              :cond (eq traced-fn 'do$) ; skip *1* call
              :entry (list traced-fn alist))
         (apply$ :cond (equal (car arglist) (@ my-body-fn))
                 :entry (list traced-fn
                              (cadr arglist) ; the alist
                        )))
 (f)
 })

 <p>Here is the trace output from the final call of @('f') above; analysis
 follows.</p>

 @({
 ACL2 !>(f)
 1> (DO$ ((X A B C) (Y)))
   2> (APPLY$ (((X A B C) (Y))))
   <2 (APPLY$ (NIL NIL ((X B C) (Y A))))
   2> (DO$ ((X B C) (Y A)))
     3> (APPLY$ (((X B C) (Y A))))
     <3 (APPLY$ (NIL NIL ((X C) (Y B A))))
     3> (DO$ ((X C) (Y B A)))
       4> (APPLY$ (((X C) (Y B A))))
       <4 (APPLY$ (NIL NIL ((X) (Y C B A))))
       4> (DO$ ((X) (Y C B A)))
         5> (APPLY$ (((X) (Y C B A))))
         <5 (APPLY$ (:RETURN (C B A) ((X) (Y C B A))))
       <4 (DO$ (C B A))
     <3 (DO$ (C B A))
   <2 (DO$ (C B A))
 <1 (DO$ (C B A))
 (C B A)
 ACL2 !>
 })

 <p>First consider the calls of @('do$') above.  You can see that @('X') is
 initially bound in the alist to @('(A B C)'), but on successive @('do$')
 calls, @('X') is bound to successive @('cdr')s of @('(A B C)').  Meanwhile,
 the accumulator variable @('Y') is initially bound to @('NIL') but at each
 call of @('do$'), the next @('car') of @('(A B C)') is pushed onto the binding
 of @('Y').  Now consider the calls of @(tsee apply$).  Up until the last call,
 @('apply$')ing the body function results in a triple of the form @('(mv nil
 nil new-alist)'), where @('new-alist') is supplied as the alist argument for
 the next @('do$') call.  The last call of @('apply$') on the body function
 gives the result @('(mv :RETURN (C B A) new-alist)'), where @('(C B A)') is
 the value returned by the calls of @('do$').</p>

 <p>Now consider this variant of the above example, which was given above when
 introducing @('FINALLY') clauses.</p>

 @({
 ACL2 !>(loop$ with x = '(a b c)
               with y = nil
               do (cond ((consp x)
                         (progn (setq y (cons (car x) y))
                                (setq x (cdr x))))
                        (t (loop-finish)))
               finally (return y))
 (C B A)
 ACL2 !>
 })

 <p>The corresponding @('do$') call is similar to that of the preceding
 example, but notice @(':LOOP-FINISH') in place of @(':RETURN'), and notice
 that we show the fourth argument this time: the function corresponding to the
 @('FINALLY') clause.</p>

 @({
 (DO$ ; Measure Function
      (LAMBDA$ (ALIST)
               (LET ((X (CDR (ASSOC-EQ-SAFE 'X ALIST)))
                     (Y (CDR (ASSOC-EQ-SAFE 'Y ALIST))))
                    (ACL2-COUNT X)))
      ; Initial Alist
      (LIST (CONS 'X '(A B C))
            (CONS 'Y NIL))
      ; Body Function
      (LAMBDA$ (ALIST)
               (LET ((X (CDR (ASSOC-EQ-SAFE 'X ALIST)))
                     (Y (CDR (ASSOC-EQ-SAFE 'Y ALIST))))
                    (IF (CONSP X)
                        (LIST NIL
                              NIL ; irrelevant
                              (LIST (CONS 'X (CDR X))
                                    (LIST* 'Y (CAR X) Y)))
                        (LIST :LOOP-FINISH
                              NIL ; irrelevant
                              (LIST (CONS 'X X) (CONS 'Y Y))))))
      ; FINALLY function
      (LAMBDA$ (ALIST)
               (LET ((X (CDR (ASSOC-EQ-SAFE 'X ALIST)))
                     (Y (CDR (ASSOC-EQ-SAFE 'Y ALIST))))
                    (LIST :RETURN
                          Y
                          (LIST (CONS 'X X) (CONS 'Y Y)))))
      ; Values (output signature)
      '(NIL)
      ... ; Last argument omitted here.
 )
 })

 <p>Above, we also took the opportunity to show the fifth argument of @('do$'),
 which is the output signature of the logical value to be returned should the
 measure fail to decrease.  That output signature is specified with the
 @(':VALUES') keyword in a @('do') @('loop$').  If omitted and the @('loop$')
 returns a single ordinary object, the output signature is @('(nil)') as here.
 The @('values') argument to @('do$') is passed along unchanged as the function
 iterates and, should the measure fail to decrease, the signature is used to
 compute a default answer.  However, that default answer is never relevant to
 evaluations because a hard ACL2 error actually occurs.  The default answer may
 be relevant when reasoning about @('do$') calls.  Since guard verification of
 a @('do') @('loop$') guarantees termination, the default answer is never
 relevant when dealing with guard verified functions containing @('do')
 @('loop$')s.</p>

 <p>Here is the definition of @(tsee do$).</p>

 @(def do$)

 <p>We conclude by returning to an earlier example that illustrates runtime
 guard-checking.  But this time we do some tracing, as indicated.</p>

 @({
 (defun f (lst)
   (loop$ with x = lst
          do
          :guard (consp x)
          (cond ((consp x)
                 (setq x (cdr x)))
                (t (return x)))))
 (trace! (do$ :entry (list traced-fn alist) :notinline t))
 (trace$ do-body-guard-wrapper)
 })

 <p>As before, we have a guard violation.  The trace output is explained
 below.</p>

 @({
 ACL2 !>(f '(a b c d))
 1> (ACL2_*1*_ACL2::DO$ ((X A B C D)))
   2> (DO$ ((X A B C D)))
     3> (DO-BODY-GUARD-WRAPPER T NIL)
     <3 (DO-BODY-GUARD-WRAPPER T)
     3> (DO-BODY-GUARD-WRAPPER T NIL)
     <3 (DO-BODY-GUARD-WRAPPER T)
     3> (DO-BODY-GUARD-WRAPPER T NIL)
     <3 (DO-BODY-GUARD-WRAPPER T)
     3> (DO$ ((X B C D)))
       4> (DO-BODY-GUARD-WRAPPER T NIL)
       <4 (DO-BODY-GUARD-WRAPPER T)
       4> (DO-BODY-GUARD-WRAPPER T NIL)
       <4 (DO-BODY-GUARD-WRAPPER T)
       4> (DO-BODY-GUARD-WRAPPER T NIL)
       <4 (DO-BODY-GUARD-WRAPPER T)
       4> (DO$ ((X C D)))
         5> (DO-BODY-GUARD-WRAPPER T NIL)
         <5 (DO-BODY-GUARD-WRAPPER T)
         5> (DO-BODY-GUARD-WRAPPER T NIL)
         <5 (DO-BODY-GUARD-WRAPPER T)
         5> (DO-BODY-GUARD-WRAPPER T NIL)
         <5 (DO-BODY-GUARD-WRAPPER T)
         5> (DO$ ((X D)))
           6> (DO-BODY-GUARD-WRAPPER T NIL)
           <6 (DO-BODY-GUARD-WRAPPER T)
           6> (DO-BODY-GUARD-WRAPPER NIL NIL)
           <6 (DO-BODY-GUARD-WRAPPER NIL)


 ACL2 Error [Evaluation] in TOP-LEVEL:  The guard for a DO$ form,
 (AND (ALISTP ALIST) (CONSP (CDR (ASSOC-EQ-SAFE 'X ALIST)))),
  has been violated by the following alist:
 ((X)).
 See :DOC do-loop$.

 ACL2 !>
 })

 <p>To understand the trace output above, we first take a look at the
 translation of the @('loop$') expression above.  This time we show the
 corresponding @('do$') form with @(tsee declare) forms included, but as
 before some parts of this form are simplified, untranslated, or elided.  (You
 can see the exact translation by applying @(':')@(tsee trans) to the @('do$')
 call.)  Note that @('do-body-guard-wrapper') is just an identity function (on
 its first argument) used by the implementation, but it is handy here for the
 explanation that follows.</p>

 @({
 (DO$
   ;; measure:
   '(LAMBDA (ALIST)
     (DECLARE
      (XARGS :GUARD
             (DO-BODY-GUARD-WRAPPER
              (AND (ALISTP ALIST)
                   (CONSP (CDR (ASSOC-EQ-SAFE 'X ALIST))))
              NIL)))
     ((LAMBDA (X) (ACL2-COUNT X))
      (CDR (ASSOC-EQ-SAFE 'X ALIST))))
   ;; alist:
   (LIST (CONS 'X LST))
   ;; body:
   '(LAMBDA (ALIST)
     (DECLARE
      (XARGS :GUARD
             (DO-BODY-GUARD-WRAPPER
              (AND (ALISTP ALIST)
                   (CONSP (CDR (ASSOC-EQ-SAFE 'X ALIST))))
              NIL)))
     ((LAMBDA (X)
              (IF (CONSP X)
                  (LIST NIL NIL
                        (LET ((X (CDR X))) (LIST (CONS 'X X))))
                  (LIST :RETURN X (LIST (CONS 'X X)))))
      (CDR (ASSOC-EQ-SAFE 'X ALIST))))
   .....)
 })

 <p>Recall that @('do$') works by repeatedly applying the given lambda to its
 alist argument, which initially binds @(''X') to @('LST') as shown above.
 @('Do$') recurs when that application returns a triple @('(mv nil nil
 new-alist)'), where @('new-alist') is the alist returned by the body of the
 @('loop$') expression.  But when @('do$') applies the given @(see lambda)
 object, it first checks the @(':guard') of that lambda.  We also see that
 before @('do$') recurs, it applies its @('measure-fn') argument to the input
 alist and to @('new-alist').</p>

 <p>So let's focus on the following from the end of the trace output above.</p>

 @({
         5> (DO$ ((X D)))
           6> (DO-BODY-GUARD-WRAPPER T NIL)
           <6 (DO-BODY-GUARD-WRAPPER T)
           6> (DO-BODY-GUARD-WRAPPER NIL NIL)
           <6 (DO-BODY-GUARD-WRAPPER NIL)
 })

 <p>The first @('DO-BODY-GUARD-WRAPPER') call comes from the guard of the
 lambda that represents the body of the @('do$') loop, from the expression
 @('(apply$ do-fn (list alist))') in the definition of @('do$') (above).  Here
 @('alist') is @('((X D))'), so the conjunct @('(CONSP (CDR (ASSOC-EQ-SAFE 'X
 ALIST)))') from that lambda's guard is true.  The second call of
 @('DO-BODY-GUARD-WRAPPER') comes from the expression @('(apply$
 measure-fn (list new-alist))') in the definition of @('do$').  But
 @('new-alist') is @('nil'), so the conjunct @('(CONSP (CDR (ASSOC-EQ-SAFE 'X
 ALIST)))') from the measure lambda's guard is false, so the guard evaluates to
 @('nil').</p>

 <h3>SIGNALING ERRORS</h3>

 <p>We explain the subtleties of error signaling from within @('DO')
 @('loop$')s by example.  To illustrate the full complexity of the situation,
 our example will involve a @('DO') that is manipulating a @(see stobj), and
 we'll verify the guards.  The basic idea is that we'll define a function,
 called @('transaction'), that either detects and signals an error or updates
 the stobj, and then we'll write a @('DO') @('loop$') that executes a series of
 transactions.  In fact, you may think of the stobj as representing an account
 that must maintain a non-negative balance and the transaction as taking an
 integer and adding it to the balance provided that doesn't produce a negative
 balance.  Managing the signatures of the various functions in body of the
 @('loop$') and declaring the ``right'' guards takes some experience.  After
 we've presented a correct solution we will show some plausible alternatives
 and explain why they are unacceptable.</p>

 <p>Recall that the standard idiom for signaling a ``soft'' error in ACL2 is to
 call the function @(tsee error1), usually via the macro @(tsee er).
 @('Error1') returns an @(see error-triple) of the form @('(mv t nil state)').
 So our @('DO') @('loop$') will necessarily manipulate @('state') in addition
 to the user's stobj.</p>

 <p>To admit the functions shown below, first execute these three commands.</p>

 @({
 (include-book "projects/apply/top" :dir :system)
 (set-state-ok t)
 (defstobj st (balance :type (satisfies natp) :initially 0))
 })

 <p>Note that our stobj has just one field, named @('balance'), which must be a
 natural number and is initially 0.  Below is the basic @('transaction')
 function which may signal an error.  Note that two unnecessary lines are
 commented out as explained in note [1] below.</p>

 @({
  (defun transaction (delta st state)
    (declare (xargs :stobjs (st state)
                    :guard (and (integerp delta)
  ;                             (stp st)                     ; [1]
  ;                             (state-p state)              ; [1]
                                (error1-state-p state))))    ; [2]
    (cond ((< (balance st) (- delta))
           (mv-let (erp val state)                           ; [3]
             (er soft 'transaction
                 "The stobj's balance is ~x0 but the delta is ~x1, so this ~
                  transaction is not allowed!"
                 (balance st)
                 delta)
             (declare (ignore val))
             (mv erp st state)))
          (t (let ((st (update-balance (+ (balance st) delta)
                                       st)))
               (mv nil st state)))))
  })

  <p>Notes on @('transaction'):</p>

  <ul>

  <li>[1] We don't need to include @('(stp state)') and @('(state-p state)')
    explicitly in the @(':guard') for the function because they're implicitly
    included by the @(':stobjs') declaration.</li>

  <li>[2] The @(tsee er) macro expands to a call of the function @(tsee
    error1), and @('error1') requires that its @(tsee state) argument not only
    satisfy the recognizer for ACL2 states, @('state-p'), but also some
    other conditions to allow formatted printing to certain channels.  See
    @(':')@(tsee pe) @('error1-state-p') and its subroutine @('fmt-state-p').
    By the way, you won't see ``@('(state-p state)')'' in the @(':guard')
    declaration of @('error1').  But it is implicit in the use of the variable
    named @('state') as a formal.  To see the full guard of a function,
    <i>fn</i>, you can do @(':')@(tsee args) <i>fn</i> or,
    alternatively, @('(guard '')<i>fn</i>@(' nil (w state))').</li>

  <li>[3] We signal an error with the @('er') macro.  But the signature of
    @('er') is @('(mv * * state)'), i.e., the first two values returned are
    ``ordinary'' objects, not stobjs.  But our function, @('transaction'), must
    return the (possibly) modified stobj @('st').  So we ``catch'' the error
    triple generated by @('er') and replace the ordinary @('val'), which in
    this case is @('nil'), by @('st').</li>
  </ul>

 <p>Since we'll use @('transaction') in a @('DO') @('loop$'), we need a
 warrant.</p>

 @({
 (defwarrant transaction)
 })

 <p>The lemma below is not strictly necessary.  If we don't prove it here, the
 guard proof for our @('loop$') takes longer because we have to prove a more
 complicated instance of this lemma by induction.</p>

 @({
 (defthm dumb-lemma
   (implies (and lst
                 (integer-listp lst))
            (integerp (car lst)))
   :rule-classes :type-prescription)
 })

 <p>Finally, we define the function that executes a series of @('transaction')s
 on a sequence of integers.  But it may detect and signal an error partway
 through the sequence.  Note that several lines are commented out, either
 because they are optional or because they are prohibited, as explained in the
 accompanying notes below.</p>


 @({
 (defun transaction-loop (delta-lst st state)
   (declare (xargs :stobjs (st state)
                   :guard (and (integer-listp delta-lst)
 ;                             (stp st)                     ; See Note [1] above
 ;                             (state-p state)              ; See Note [1] above
                               (error1-state-p state))
                   :guard-hints (("Goal" :in-theory (enable error1)))))
   (loop$ with lst = delta-lst
 ;        with st                                           ; [4]
 ;        with state                                        ; [4]
          with erp                                          ; [5]
          do
          :guard (and (integer-listp lst)
                      (stp st)                              ; [6]
                      (state-p state)                       ; [6]
                      (error1-state-p state))
          :values (nil st state)
          (cond
           ((eq lst nil) (return (mv nil st state)))
           (t (progn                                        ; [7]
                (mv-setq (erp st state)
                         (transaction (car lst) st state))
                (cond
                 (erp (return (mv erp st state)))
                 (t (setq lst (cdr lst)))))))))
 })

 <p>Notes on @('transaction-loop'):</p>

 <ul>

 <li>[4] One might think that we need to bind @('st') and @('state') in
     @('WITH') clauses because, in the body of the @('DO') @('loop$'), we
     assign to them, with @('mv-setq'), here, or in other examples, with
     @('setq').  But ACL2 disallows binding stobj names in @('WITH') clauses.
     A syntax error is signaled if you try that.</li>

 <li>[5] We must bind @('erp') in a @('WITH') clause because we assign to it
     in the body and it is an ordinary object.</li>

 <li>[6] One might think that we do not need to include @('(stp st)') and
     @('(state-p state)') in the @(':guard') of the @('DO') @('loop$') body,
     for the same reasons we did not have to include them in the @(':guard') of
     the function itself: might they be implicitly included by virtue of their
     being stobj names?  The answer is no!  If a stobj is used in the body of a
     @('DO') @('loop$'), the @(':guard') for the @('DO') @('loop$') must
     include the stobj recognizer if guard checking is to succeed.</li>

 <li>[7] Finally, the construction

     @({
     (progn (mv-setq (erp st state) <term>) <do-body-term>)
     })

     used here may seem odd.  One might be inclined to write something like
     this instead:

     @({
     (mv-let (erp st state) <term> <do-body-term>)
     })

     However, the latter construction is syntactically illegal in the body
     of a @('DO') @('loop$').  The reason has to do with the precise definition
     of ``do-body terms'' (see the SYNTAX section above).  Recall that do-body
     terms are term-like but allow very restricted uses of @('return'),
     @('progn'), @('setq'), @('mv-setq'), and @('loop-finish') and possibly
     other do-body subterms.  Do-body terms are not actually ACL2 terms!

     <p/>To be precise, one might have tried to use the following as the body
     of the @('loop$') in @('transaction-loop').

     @({
     (cond
       ((eq lst nil) (return (mv nil st state)))
       (t (mv-let (erp st state)
                  (transaction (car lst) st state)
            (cond
             (erp (return (mv erp st state)))
             (t (setq lst (cdr lst)))))))
     })

     Note the @('mv-let').  It is syntactically illegal because its final
     argument, namely the @('cond')-expression, uses @('return') and @('setq')
     where ACL2 function names are required.  In writing the above, the user
     has presumed that an @('mv-let') expression in a do-body term allows the
     final argument to be a do-body term instead of an ACL2 term.  This
     presumption is incorrect.  Instead, use @('progn') and @('mv-setq') to
     field the values of a multi-valued function like @('transaction') and then
     write the do-body term to process them.</li>

 </ul>

 <p>Here is a sample session log after introducing the correct definitions
 above.  Note that the balance starts at 0, the user, employing the function
 @('transaction'), adds 100 and then attempts to subtract 150.  An error is
 signaled and the balance remains 100.  Then the user runs the
 @('transaction-loop') function with a starting balance of 100 and attempts to
 successively subtract 20, then 30, then 55, and then attempts to add 200.  The
 loop terminates with an error on the 55 and leaves the balance at 50, never
 processing the 200.</p>

 @({
 ACL2 !>(balance st)
 0
 ACL2 !>(transaction 100 st state)
 (NIL <st> <state>)
 ACL2 !>(balance st)
 100
 ACL2 !>(transaction -150 st state)


 ACL2 Error in TRANSACTION:  The stobj's balance is 100 but the delta
 is -150, so this transaction is not allowed!

 (T <st> <state>)
 ACL2 !>(balance st)
 100
 ACL2 !>(transaction-loop '(-20 -30 -55 200) st state)


 ACL2 Error in TRANSACTION:  The stobj's balance is 50 but the delta
 is -55, so this transaction is not allowed!

 (T <st> <state>)
 ACL2 !>(balance st)
 50
 })

 ")

(defxdoc do-not
  :parents (hints)
  :short "Instruct the theorem prover not to do certain things."
  :long "<p>See @(see hints) for documentation about the @(':do-not') keyword
 for prover @(':hints').</p>

 <p>See @(see do-not-hint) for documentation about the @('do-not') macro that
 controls a mechanism for automatically suggesting @(':do-not') and
 @(':do-not-induct') hints.</p>")

(defxdoc doc
  :parents (documentation)
  :short "@(see Documentation) at the terminal"
  :long "<p>The @(':doc') command may be used at the ACL2 prompt to access the
 ACL2 system @(see documentation).  Usually (when the @(see xdoc) system has
 been included) it can also access other documentation topics defined in the
 current session, including via included books.  However, most users will
 probably access the ACL2 documentation in other ways; see @(see
 documentation).  In particular, consider using the
 @(`(:raw (combined-manual-ref))`), for topics documented in the ACL2 community
 @(see books) or in the ACL2 system (where the latter are rearranged).</p>

 <p>If you are not happy with the way text is displayed using @(':doc'), see
 @(see xdoc::terminal).</p>

 <p>Alternatively, consider using the ACL2-Doc Emacs browser; see @(see
 ACL2-Doc).</p>

 @({
  Examples:
  ACL2 !>:doc DEFTHM          ; print documentation of DEFTHM
  ACL2 !>:doc logical-name    ; print documentation of LOGICAL-NAME

  General Form:
  ACL2>:doc name
 })

 <p>Note that links are always printed with respect to the @('"ACL2"')
 package (that is, as though the current package were @('"ACL2"')).  So for
 example, a link to the present topic will be displayed as @('[doc]'), not as
 @('[acl2::doc]'), regardless of the current package or the package of the
 topic being displayed.  Such links can thus take you to topics in the ACL2-Doc
 Emacs browser (see @(see ACL2-Doc)).</p>

 <p>Note that @(see community-book) @('xdoc/top') redefines @(':doc') (using
 @(see add-ld-keyword-alias!)) to invoke the similar macro @('xdoc'), which can
 access documentation topics defined in books.</p>")

(defxdoc doc-terminal-test-1
  :parents (documentation)
  :short "Short"
  :long "<p><b>Symbol @('EQUAL') and the rest is still bold.</b></p>")

(defxdoc doc-terminal-test-2
  :parents (documentation)
  :short "Short"
  :long "<p><u>Start underline <b>Start bold <i>Start italics <tt>TYPEWRITER
 FONT [WHICH ENDS HERE]</tt> Bold italics underlined</i> Bold underlined.</b>
 Underlined</u> Normal text</p>")

(defxdoc documentation
  :parents (top)
  :short "Information about options for downloading and viewing the ACL2
 documentation, contributing documentation, and the available tools for
 documenting your own books."
  :long "<h3>Available Documentation</h3>

 <p>If you are new to ACL2, see the @(see acl2-tutorial) for introductory
 tours, tutorials, and information about textbooks about ACL2.  The <a
 href='http://www.cs.utexas.edu/users/moore/acl2'>ACL2 home page</a> also
 provides many links to academic publications about ACL2, including the ACL2
 Workshop series.</p>

 <p>Beyond these resources, there is a vast <b>ACL2+Books Manual</b> with
 reference material covering the ACL2 system itself and also many @(see
 community-books).  There are a few ways to access the manual:</p>

 <ul>

 <li><b>The online version (recommended).</b> If you expect to have an internet
 connection while using the documentation, you may prefer to use the online
 version of the @(`(:raw (combined-manual-ref))`).</li>

 <li><b>A local version.</b> If you sometimes work without an internet
 connection, you can <a href='download/'>download</a> a local copy of any
 web-based XDOC manual using the "down arrow" icon at the top of the page.
 You can alternately build your own copy of the manual; see <i>Building
 the manual</i> in @(see books-certification).</li>

 <li><b>The ACL2-Doc Emacs version.</b> If you would like to view the
 documentation using Emacs instead of a web browser, there is a feature-rich
 Emacs-based documentation browser provided by the ACL2 system.  See @(see
 acl2::acl2-doc) for details.</li>

 </ul>

 <p>While you are using ACL2, you can get documentation at the terminal with
 the @(':')@(tsee doc) command, e.g., by typing @(':doc rewrite').  This is
 often handy, but note that it won't show you any documentation for books that
 you haven't loaded yet!</p>

 <p>When you type @(':DOC <topic>') at the terminal for a given @('<topic>'),
 ACL2 responds with documentation for that topic.  Unless you include books
 that incorporate additional documentation, @('<topic>') must be documentation
 that is provided with the ACL2 system (not the @(see community-books)).</p>

 <h3>Documenting Your Books</h3>

 <p>Documentation is written using @(see xdoc), and may be found in the @(see
 community-books).  Everyone is welcome to edit and contribute to that
 documentation.  In particular, you are welcome to edit the book that contains
 ACL2 system documentation, @('books/system/doc/acl2-doc.lisp').  (Please do
 not edit ACL2 source file @('doc.lisp'), which is generated from that book.
 More generally, edit only files under the @('books/') directory.)</p>

 <p>You can also use XDOC to document your own books and to build custom
 manuals for your organization.</p>

 <p><b>Remark for Experienced Users</b>.  Occasionally it might make sense to
 add a link to your book's documentation from the ACL2 system documentation,
 which is in @(see community-book) @('books/system/doc/acl2-doc.lisp'). You are
 welcome to do so, but in that case, also add to the constant
 @('*acl2-broken-links-alist*') near the top of that file, as described in a
 comment in that constant.  For example, that constant's value has the
 following line.</p>

 @({
     (FTY::DEFPROD "[books]/centaur/fty/top.lisp")
 })

 <p>That line may have been added because in the form @('(defxdoc defrec ...)')
 in @('acl2-doc.lisp'), we find a link to @('fty::defprod').  You can do
 similarly for your own added link.</p>

 <p>If your topic is not in the @('"ACL2"') package, such as in the example
 link @('fty::defprod') above, then add a suitable @(tsee include-book) form to
 @('books/system/doc/cert.acl2').  For example, that file includes the line</p>

 @({
 (include-book "centaur/fty/portcullis" :dir :system)
 })

 <p>in order to define the @('"FTY"') package.  End of Remark for
 Experienced Users</p>

 <h3>Other Resources</h3>

 <p>If you want documentation on an ACL2 function or macro that is not
 documented, there are still several alternatives.</p>

 @({
  ACL2 !>:args fn
 })

 <p>will print the arguments and some other relevant information about the
 named function or macro.  This information is all gleaned from the definition
 and hence this is a definitive way to determine if @('fn') is defined as a
 function or macro.</p>

 <p>You might also want to type:</p>

 @({
  ACL2 !>:pc fn
 })

 <p>which will print the @(see command) that introduced @('fn').  You should
 see @(see command-descriptor) for details on the kinds of input you can give
 the @(':')@(tsee pc) command.</p>")

(defxdoc documentation-copyright
  :parents (copyright documentation)
  :short "Copyright and authorship of documentation"
  :long "<p>There are two manuals associated with ACL2: the ACL2 User's Manual
 and the ACL2+Books Manual.  See @(see documentation).  The former is
 distributed with ACL2, you can reach many links into it from the ACL2 home
 page.  The latter may be preferred for routine browsing, since it extends the
 ACL2 User's Manual with documentation obtained from the @(see
 community-books).</p>

 <p>The ACL2 User's Manual is the basis for using the @(':')@(tsee DOC) command
 at the terminal when ACL2 starts up.  Its source in the ACL2 @(see
 community-books) as file @('books/system/doc/acl2-doc.lisp').  Members of the
 ACL2 community contribute to it, although its original authors are the ACL2
 authors.  It is copyrighted under the terms of the @('LICENSE') file
 distributed with ACL2.</p>

 <p>The ACL2+Books Manual is a mechanically generated mashup derived from both
 the ACL2 User's Manual and the @(see community-books).  The ACL2+Books Manual
 thus has contributions from many authors.  At the top of each topic, in a line
 under the topic name, you will generally find either ``ACL2 Sources'' or the
 name of a Community Book.  In the former case, the text is from the ACL2
 User's Manual and is authored, copyrighted, and licensed as per the ACL2 @(see
 copyright).  When a book is named, the content was extracted from that book
 which may be inspected for authorship, copyright, and license terms.</p>

 <p>There are two standard tools for browsing these manuals, other than using
 the @(':')@(tsee doc) command at the terminal.</p>

 <ul>

 <li><b>The ACL2 @(csee xdoc) Fancy Viewer.</b> This tool, written by Jared
 Davis, is included with the web-based version of each manual.  Information on
 copyright and licensing are provided in <a href='LICENSE'>its LICENSE
 file</a>.</li>

 <li><b>The @(see acl2-doc) Emacs browser.</b> This tool, authored by Matt
 Kaufmann and J Strother Moore, is distributed with ACL2 and is licensed under
 the terms of the @('LICENSE') file distributed with ACL2.</li>

 </ul>")

(defxdoc double-rewrite
  :parents (rewrite)
  :short "Cause a term to be rewritten twice"
  :long "<p>Logically, @('double-rewrite') is the @(tsee identity) function:
 @('(double-rewrite x)') is equal to @('x').  However, the ACL2 rewriter treats
 calls of @('double-rewrite') in the following special manner.  When it
 encounters a term @('(double-rewrite u)'), it first rewrites @('u') in the
 current context, and then the rewriter rewrites the result.</p>

 <p>Such double-rewriting is rarely necessary, but it can be useful when
 rewriting under non-trivial equivalence relations (see @(see equivalence)).
 The following example will illustrate the issue.</p>

 @({
  ; Define an equivalence relation.
  (defun my-equiv (x y)
    (equal x y))
  (defequiv my-equiv)

  ; Define a unary function whose argument is preserved by my-equiv.
  (defun foo (x)
    (declare (ignore x))
    t)
  (defcong my-equiv equal (foo x) 1)

  ; Define some other unary functions.
  (defun g (x) x)
  (defun h1 (x) x)
  (defun h2 (x) x)

  ; Prove some lemmas and then disable the functions above.
  (defthm lemma-1
    (my-equiv (h1 x) (h2 x)))
  (defthm lemma-2
    (foo (h2 x)))
  (defthm lemma-3
    (implies (foo x)
             (equal (g x) x)))
  (in-theory (union-theories (theory 'minimal-theory)
                             '(lemma-1 lemma-2 lemma-3
                               my-equiv-implies-equal-foo-1)))

  ; Attempt to prove a simple theorem that follows ``obviously'' from the
  ; events above.
  (thm (equal (g (h1 a)) (h1 a)))
 })

 <p>We might expect the proof of this final @('thm') to succeed by the
 following reasoning.  It is immediate from @('lemma-3') provided we can
 establish @('(foo (h1 a))').  By the @('defcong') event above, we know that
 @('(foo (h1 a))') equals @('(foo (h2 a))') provided @('(my-equiv (h1 a) (h2
 a))'); but this is immediate from @('lemma-1').  And finally, @('(foo (h2
 a))') is true by @('lemma-2').</p>

 <p>Unfortunately, the proof fails.  But fortunately, ACL2 gives the following
 useful warning when @('lemma-3') is submitted:</p>

 @({
  ACL2 Warning [Double-rewrite] in ( DEFTHM LEMMA-3 ...):  In the :REWRITE
  rule generated from LEMMA-3, equivalence relation MY-EQUIV is maintained
  at one problematic occurrence of variable X in hypothesis (FOO X),
  but not at any binding occurrence of X.  Consider replacing that occurrence
  of X in this hypothesis with (DOUBLE-REWRITE X).  See :doc double-
  rewrite for more information on this issue.
 })

 <p>We can follow the warning's advice by changing @('lemma-3') to the
 following.</p>

 @({
  (defthm lemma-3
    (implies (foo (double-rewrite x))
             (equal (g x) x)))
 })

 <p>With this change, the proof succeeds for the final @('thm') above.</p>

 <p>In practice, it should suffice for users to follow the advice given in the
 ``@('Double-rewrite')'' warnings, by adding calls of @('double-rewrite')
 around certain variable occurrences.  But this can cause inefficiency in large
 proof efforts.  For that reason, and for completeness, it seems prudent to
 explain more carefully what is going on; and that is what we do for the
 remainder of this @(see documentation) topic.  Optionally, also see the paper
 ``Double Rewriting for Equivalential Reasoning in ACL2'' by Matt Kaufmann and
 J Strother Moore, in the proceedings of the 2006 ACL2 Workshop (paper is
 published in the <a href='http://portal.acm.org/toc.cfm?id=1217975'>ACM
 Digital Library</a>); you might also find it for free <a
 href='http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.90.7190&amp;rep=rep1&amp;type=pdf'>here</a>.</p>

 <p><b>Suggesting congruence rules.</b></p>

 <p>Sometimes the best way to respond to a ``@('Double-rewrite')'' warning may
 be to prove a congruence rule.  Consider for example this rule.</p>

 @({
  (defthm insert-sort-is-id
    (perm (insert-sort x) x))
 })

 <p>Assuming that @('perm') has been identified as an @(see equivalence)
 relation (see @(see defequiv)), we will get the following warning.</p>

 @({
  ACL2 Warning [Double-rewrite] in ( DEFTHM INSERT-SORT-IS-ID ...):
  In a :REWRITE rule generated from INSERT-SORT-IS-ID, equivalence relation
  PERM is maintained at one problematic occurrence of variable X in the
  right-hand side, but not at any binding occurrence of X.  Consider
  replacing that occurrence of X in the right-hand side with
  (DOUBLE-REWRITE X).  See :doc double-rewrite for more information on
  this issue.
 })

 <p>The problem is that the second occurrence of @('x') (the right-hand side of
 the rule @('insert-sort-is-id')) is in a context where @('perm') is to be
 maintained, yet in this example, the argument @('x') of @('insert-sort') on
 the left-hand side of that rule is in a context where @('perm') will not be
 maintained.  This can lead one to consider the possibility that @('perm')
 could be maintained in that left-hand side occurrence of @('x'), and if so, to
 prove the following congruence rule.</p>

 @({
  (defcong perm perm (insert-sort x) 1)
 })

 <p>This will eliminate the above warning for @('insert-sort-is-id').  More
 important, this @(tsee defcong) event would probably be useful, since it would
 allow rewrite rules with equivalence relation @('perm') to operate on the
 first argument of any call of @('insert-sort') whose context calls for
 maintaining @('perm').</p>

 <p><b>Details on double-rewrite.</b></p>

 <p>The reader who wants these details may first wish to see @(see equivalence)
 for relevant review.</p>

 <p>The ACL2 rewriter takes a number of contextual arguments, including the
 generated equivalence relation being maintained (see @(see congruence)) and an
 association list that maps variables to terms.  We call the latter alist the
 @('unify-subst') because it is produced by unifying (actually matching) a
 pattern against a current term; let us explain this point by returning to the
 example above.  Consider what happens when the rewriter is given the top-level
 goal of the @('thm') above.</p>

 @({
  (equal (g (h1 a)) (h1 a))
 })

 <p>This rewrite is performed with the empty alist (@('unify-subst')), and is
 begun by rewriting the first argument (in that same empty
 @('unify-subst')):</p>

 @({
  (g (h1 a))
 })

 <p>Note that the only equivalence relation being maintained at this point is
 @('equal').  Now, the rewriter notices that the left-hand side of
 @('lemma-3'), which is @('(g x)'), matches @('(g (h1 a))').  The rewriter thus
 creates a @('unify-subst') binding @('x') to @('(h1 a)'): @('((x . (h1 a)))').
 It now attempts to rewrite the hypothesis of @('lemma-3') to @('t') under this
 @('unify-subst').</p>

 <p>Consider what happens now if the hypothesis of @('lemma-3') is @('(foo
 x)').  To rewrite this hypothesis under a @('unify-subst') of @('((x . (h1
 a)))'), it will first rewrite @('x') under this @('unify-subst').  The key
 observation here is that this rewrite takes place simply by returning the
 value of @('x') in the @('unify-subst'), namely @('(h1 a)').  No further
 rewriting is done!  The efficiency of the ACL2 rewriter depends on such
 caching of previous rewriting results.</p>

 <p>But suppose that, instead, the hypothesis of @('lemma-3') is @('(foo
 (double-rewrite x))').  As before, the rewriter dives to the first argument of
 this call of @('foo').  But this time the rewriter sees the call
 @('(double-rewrite x)'), which it handles as follows.  First, @('x') is
 rewritten as before, yielding @('(h1 a)').  But now, because of the call of
 @('double-rewrite'), the rewriter takes @('(h1 a)') and rewrites it under the
 empty @('unify-subst').  What's more, because of the @('defcong') event above,
 this rewrite takes place in a context where it suffices to maintain the
 equivalence relation @('my-equiv').  This allows for the application of
 @('lemma-1'), hence @('(h1 a)') is rewritten (under @('unify-subst') =
 @('nil')) to @('(h2 a)').  Popping back up, the rewriter will now rewrite the
 call of @('foo') to @('t') using @('lemma-2').</p>

 <p>The example above explains how the rewriter treats calls of
 @('double-rewrite'), but it may leave the unfortunate impression that the user
 needs to consider each @(':')@(tsee rewrite) or @(':')@(tsee linear) rule
 carefully, just in case a call of @('double-rewrite') may be appropriate.
 Fortunately, ACL2 provides a ``[Double-rewrite]'' warning to inform the user
 of just this sort of situation.  If you don't see this warning when you submit
 a (@(':')@(tsee rewrite) or @(':')@(tsee linear)) rule, then the issue
 described here shouldn't come up for that rule.  Such warnings may appear for
 hypotheses or right-hand side of a @(':')@(tsee rewrite) rule, and for
 hypotheses or full conclusion (as opposed to just the trigger term) of a
 @(':')@(tsee linear) rule.</p>

 <p>If you do see a ``[Double-rewrite]'' warning, then should you add the
 indicated call(s) of @('double-rewrite')?  At the time of writing this @(see
 documentation), the answer is not clear.  Early experiments with double
 rewriting suggested that it may be too expensive to call @('double-rewrite')
 in every instance where a warning indicates that there could be an advantage
 to doing so.  And at the time of this writing, the ACL2 regression suite has
 about 1900 such warnings (but note that books were developed before
 @('double-rewrite') or the ``[Double-rewrite]'' warning were implemented),
 which suggests that one can often do fine just ignoring such warnings.
 However, it seems advisable to go ahead and add the calls of
 @('double-rewrite') indicated by the warnings unless you run across efficiency
 problems caused by doing so.  Of course, if you decide to ignore all such
 warnings you can execute the event:<br></br>

 @('(')@(tsee set-inhibit-warnings)@(' "Double-rewrite")').</p>

 <p>Finally, we note that it is generally not necessary to call
 @('double-rewrite') in order to get its effect in the following case, where
 the discussion above might have led one to consider a call of
 @('double-rewrite'): a hypothesis is a variable, or more generally, we are
 considering a variable occurrence that is a branch of the top-level @('IF')
 structure of a hypothesis.  The automatic handling of this case, by a form of
 double rewriting, was instituted in ACL2 Version_2.9 and remains in place with
 the introduction of @('double-rewrite').  Here is a simple illustrative
 example.  Notice that @('foo-holds') applies to prove the final @(tsee thm)
 below, even without a call of @('double-rewrite') in the hypothesis of
 @('foo-holds'), and that there is no ``[Double-rewrite]'' warning when
 submitting @('foo-holds').</p>

 @({
  (encapsulate
   (((foo *) => *)
    ((bar *) => *))

   (local (defun foo (x) (declare (ignore x)) t))
   (local (defun bar (x) (declare (ignore x)) t))

   (defthm foo-holds
     (implies x
              (equal (foo x) t)))
   (defthm bar-holds-propositionally
     (iff (bar x) t)))

  (thm (foo (bar y)))
 })")

(defxdoc e/d
  :parents (theories theory-functions)
  :short "Enable/disable rules"
  :long "<p>The macro @('e/d') creates theory expressions for use in @(tsee
 in-theory) hints and events.  It provides a convenient way to @(tsee enable)
 and @(tsee disable) simultaneously, without having to write arcane theory
 expressions.  For related utilities, see @(see enable) and see @(see
 disable).</p>

 @({
  Examples:
  (e/d (lemma1 (:e fn)))         ; equivalent to (enable lemma1 (:e fn))
  (e/d () (lemma))               ; equivalent to (disable lemma)
  (e/d (lemma1) (lemma2 lemma3)) ; Enable lemma1 then disable lemma2, lemma3.
  (e/d () (lemma1) (lemma2))     ; Disable lemma1 then enable lemma2.

  General Form:
  (e/d enables-0 disables-0 ... enables-n disables-n)
 })

 <p>where each @('enables-i') and @('disables-i') is a list of runic
 designators; see @(see theories), see @(see enable), and see @(see
 disable).  Note that the concluding @('disables-n') may be omitted.</p>

 <p>The @('e/d') macro takes any number of lists suitable for the @(tsee
 enable) and @(tsee disable) macros.  The event</p>

 @({
 (in-theory (e/d (e00 e01 e02 ...) (d00 d01 d02 ...)
                 ...
                 (en0 en1 en2 ...) (dn0 dn1 dn2 ...)
 })

 <p>creates a theory that is equivalent to the following sequence of @(tsee
 in-theory) events.  (An analogous similar effect takes place for
 @(':in-theory') @(see hints).</p>

 @({
 (in-theory (enable e00 e01 e02 ...))
 (in-theory (disable d00 d01 d02 ...))
 ...
 (in-theory (enable en0 en1 en2 ...))
 (in-theory (disable dn0 dn1 dn2 ...))
 })")

(defxdoc early-termination
  :parents (parallel-programming)
  :short "Early termination for @(tsee pand) and @(tsee por)."
  :long "<p>This @(see documentation) topic relates to the experimental
 extension of ACL2 supporting parallel execution and proof; see @(see
 parallelism).</p>

 <p>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') &mdash; no
 @('exprj') is evaluated in this case for @('j > i').  This so-called ``lazy
 evaluation'' of @(tsee and) terms can thus save some computation; roughly
 speaking, the smaller the @('i'), the more computation is saved.</p>

 <p>If the above call of @(tsee and) is replaced by its parallel version,
 @(tsee pand), then there can be even more opportunity for skipping work.  The
 arguments to @(tsee 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.</p>

 <p>Consider the following functions that compute whether a tree is valid (see
 @(see granularity) for a discussion of the granularity form).</p>

 @({
  (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)))))
 })

 <p>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 @(tsee pand), once one of
 those terms evaluates to @('nil'), the computations for the other terms are
 aborted and the @(tsee pand) call returns @('nil').  By using @(tsee pand), we
 can in principle attain a speedup factor greater than the number of available
 cores.</p>

 <p>The concept of early termination also applies to @(tsee por), except that
 early termination occurs when an argument evaluates to non-@('nil').</p>")

(defxdoc ec-call
  :parents (guard acl2-built-ins)
  :short "Execute a call in the ACL2 logic instead of raw Lisp"
  :long "<p>The name ``@('ec-call')'' represents ``executable-counterpart
 call.''  This utility is intended for users who are familiar with guards.  See
 @(see guard) for a general discussion of guards.</p>

 <p>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.</p>

 @({
  General Forms:
  (ec-call (fn term1 ... termk))
  (ec-call (fn term1 ... termk) :dfs-in 'dfs-in :dfs-out dfs-out)
 })

 <p>where @('fn') is a known function symbol other than those in the list that
 is the value of the constant @('*ec-call-bad-ops*').  (But see the Note on
 Inlining below for an exception pertaining to inlining.)  In particular,
 @('fn') is not a macro.  The second form is only relevant for those who use
 @(see df)s and is discussed at the end of this topic.</p>

 <p>Semantically, @('(ec-call (fn term1 ... termk))') equals @('(fn term1
 ... termk)').  However, this use of @('ec-call') has two effects.</p>

 <blockquote>

 <p>(1) @(see Guard) verification generates no proof obligations from the guard
 of @('fn') for this call.  Indeed, guards need not have been verified for
 @('fn').</p>

 <p>(2) During evaluation, after the arguments of @('fn') are evaluated as
 usual, the executable-counterpart of @('fn') is called, rather than its
 submitted version (see @(see evaluation)).  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 @(see guard) of
 @('fn') is checked, at least by default (see @(see
 set-guard-checking)).</p></blockquote>

 <p>The use of @('ec-call') does not turn off guard-checking, but that can be
 accomplished by using @(tsee with-guard-checking) as well.  Consider the
 following example.</p>

 @({
 (defun f1 (x)
   (declare (xargs :guard t))
   (ec-call (nth t x)))
 })

 <p>This definition is admitted, but evaluation of @('(f1 '(a b c))')
 nevertheless causes a guard violation (at least, by default).  However, if
 instead we submit the following definition, then there is no guard violation
 for that call of @('f1').</p>

 @({
 (defun f1 (x)
   (declare (xargs :guard t))
   (with-guard-checking nil (ec-call (nth t x))))
 })

 <p>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')).</p>

 <p><b>Technical Remark</b> (probably best ignored).  During evaluation of a
 call of @(tsee defconst) or @(tsee 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 @(tsee
 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.</p>

 <p>Here is another small example.  We define @('foo') recursively but with
 guard verification inhibited on the recursive call, which is to be evaluated
 in the ACL2 logic.</p>

 @({
  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 !>
 })

 <p>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
 @(see trace$) and see @(see trace)).  Each call of the executable-counterpart
 of @('foo') checks the guard and then invokes the submitted version of
 @('foo') (see @(see evaluation)).  The submitted version calls the
 executable-counterpart on the recursive call.  When the guard check fails we
 get a violation.</p>

 @({
  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 !>
 })

 <p>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.</p>

 @({
  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 >
 })

 <p>Note on Inlining.  Although in general, the form @('(ec-call (fn term1
 ... termk))') is only legal if @('fn') is a function symbol, such a form is
 also legal if @('fn') is introduced with @(tsee defun-inline), or with @(tsee
 define) using keyword argument @(':inline t').  In those cases, @('fn') is a
 macro whose calls expand to corresponding calls of @('fn$INLINE'), the symbol
 in the same package as @('fn') but with the string @('"$INLINE"') added as a
 suffix to the @(tsee symbol-name) of @('fn').  We do not however extend this
 exception to macros in general, even when @(tsee add-macro-fn) has been
 invoked.  Consider the following example.</p>

 @({
 (encapsulate
  ()
  (defun foo () nil)
  (defun bar () t)
  (defmacro mac () nil)
  (add-macro-alias mac foo)
  (local (add-macro-alias mac bar))
  (defun h () (ec-call (mac)))
  (defthm bad (h)))
 })

 <p>Consider what would happen if this were legal, where @('(ec-call (mac))')
 used the macro-alias, @('foo'), for @('mac').  Then in the first pass of the
 @(tsee encapsulate) form above, the final @(tsee defthm) event would prove,
 since (ec-call (mac)) is treated as (ec-call (bar)).  But on the second pass,
 ACL2 would store @('bad') as a theorem even though @('(h)') would evaluate to
 @('nil'), since the macro-alias of @('mac') is @('foo') on the second
 pass.</p>

 <p>We conclude with a discussion of the second General Form:</p>

 @({
  (ec-call (fn term1 ... termk) :dfs-in 'dfs-in :dfs-out 'dfs-out)
 })

 <p>Note that either or both keyword arguments may be omitted, and if both are
 included then they can be given in either order.</p>

 <p>See @(see df) for background on dfs.  Here is an example.</p>

 @({
 ACL2 !>(ec-call (binary-df+ (df1) (df1)) :dfs-in '(t t) :dfs-out '(t))
 #d2.0
 ACL2 !>
 })

 <p>The keyword arguments indicate, respectively, @('binary-df+') takes two df
 arguments and returns a single df value.  Without those arguments ACL2 would
 report an error.</p>

 <p>The next example illustrates the use of @(':dfs-out') for multiple value
 returns.  First define @('g') as follows.</p>

 @({
 (defun g (x)
   (mv (df+ (df1) (to-df x)) (- x 1)))
 })

 <p>The use of @(':dfs-out') below tells ACL2 that the given expression @('(g
 3)') returns two values: a df and an ordinary value.  In the language of :DOC
 @(see df): @('(g 3)') is a df{0} expression and is not a df{1} expression.
 Note that the argument of @('g') is an ordinary expression, not a df, so no
 @(':dfs-in') argument is necessary.</p>

 @({
 ACL2 !>(ec-call (g 3) :dfs-out '(t nil))
 (#d4.0 2)
 ACL2 !>
 })

 <p>Returning to the second General Form, notice that @('dfs-in') and
 @('dfs-out') are lists of Booleans, which must be quoted, that indicate for
 @('fn') which inputs or values (respectively) are dfs.  For example, if
 @('fn') returns a single value, then @('dfs-out') is @('(t)') if the call of
 @('fn') is a df, else @('dfs-out') is optional but may be supplied as
 @('(nil)').  If @('fn') returns n values where n is greater than 1, then
 @('dfs-out') should be a list of length n where for each zero-based index i
 less than n, the ith element of @('dfs') is @('t') if the ith return value is
 a df (or more precisely, in the language of :DOC @(see df), calls of @('fn')
 are df{i} expressions), else @('nil').  The rules for the @(':dfs-in')
 argument are analogous for inputs of the call of @('fn').</p>

 <p>When there are no df inputs (respectively, outputs) of the call, then
 @(':dfs-in') (respectively, @(':dfs-out') may be omitted or supplied as
 @('nil') or @(''nil').</p>")

(defxdoc efficiency
  :parents (debugging proof-automation programming)
  :short "Efficiency considerations"
  :long "<p>This topic is a grab-bag of ideas for the efficient use of ACL2,
 including proofs and programming.  It is far from complete, and @(see tips)
 for using ACL2 effectively may be found throughout the @(see documentation).
 The present topic will, ideally, improve over time, both in its content and in
 its organization.  Please contribute!</p>

 <p>Here we discuss primarily time efficiency rather than space efficiency.
 You can time forms using @(tsee time$).  That may show you that your tweaks
 to proof scripts or function definitions don't make a noticeable difference!
 We focus below on some techniques that have a reasonable chance of making a
 difference.</p>

 <h3>Proof efficiency</h3>

 <p>Perhaps the most basic idea for carrying out proofs efficiently is to use
 rewriting effectively; see @(see introduction-to-the-theorem-prover) and, in
 particular, the sections on rewriting.  Here we mention just a few common ways
 to improve the efficiency of rewriting in ACL2.</p>

 <ul>

 <li>Consider minimizing the number of hypotheses of a rule.  See @(see
 remove-hyps) for a tool that can help with that.</li>

 <li> Manage @(see theories) effectively.  See @(see accumulated-persistence)
 for a way to identify rules that might best be @(see disable)d.  In
 particular, it can be useful to disable functions whose expansions generate
 large case splits (see @(see splitter)); otherwise, sometimes it can be useful
 to limit case-splits with @(tsee set-case-split-limitations).</li>

 <li>When many similar proofs are being performed (for example, for families of
 similar theorems generated by macros), the tool @(see removable-runes) may be
 helpful.</li>

 </ul>

 <p>Sometimes rewriting is slow for inherent algorithmic reasons.  For example,
 if you have a binary function, @('op'), and you prove the @(see rewrite) rules
 @('(equal (op x y) (op y x)')) and @('(equal (op x (op y z)) (op y (op x
 z)))'), then ACL2 will use an @('n^2') algorithm to put arguments in order,
 essentially with bubblesort, in a sequence like this:</p>

 @({
 (op d (op c (op b a)))
 (op d (op c (op a b)))
 (op d (op a (op c b)))
 (op d (op a (op b c)))
 (op a (op d (op b c)))
 (op a (op b (op d c)))
 (op a (op b (op c d)))
 })

 <p>In such a case, you may find it very helpful to create a suitable @(see
 meta) rule or a @(see clause-processor) rule, to implement an @('n*log(n)')
 algorithm.  You may consider creating calls of @(tsee hide) to avoid exploring
 terms that are in the expected form.  Calls of @('hide') may be removed when
 ready either with a suitable @(':expand') hint or by enabling a @(see rewrite)
 rule @('(equal (hide x) x)').</p>

 <p>We conclude this section with ways to tweak the ACL2 system to speed up
 slow proofs.  These can be especially useful if very large terms are involved.
 One simple thing to try is to turn off the rewrite cache.</p>

 @({
 (set-rw-cache-state nil)
 })

 <p>Some system behaviors can be modified using @(tsee defattach-system)
 &mdash; also see @(see system-attachments) &mdash; typically by modifying
 heuristics.  You can find all attachments by evaluating @('(all-attachments (w
 state))') and all built-in such attachments by evaluating @('(global-val
 'attachments-at-ground-zero (w state))'), except for a few exceptions (see
 @(see defattach)).  For most of these, however, you will need to consult the
 ACL2 source files for relevant information.  Here are some key examples of how
 to modify system behavior.</p>

 @({
 (defun constant-nil-function-arity-2 (x y)
   (declare (xargs :mode :logic :guard t) (ignore x y))
   nil)
 (defattach-system too-many-ifs-post-rewrite
   constant-nil-function-arity-2)
 (defattach-system too-many-ifs-pre-rewrite
   constant-nil-function-arity-2)
 (defattach-system quick-and-dirty-srs
   constant-nil-function-arity-2)
 })

 <p>In some cases books may provide more sophisticated uses of @(tsee
 defattach-system) (or @(tsee defattach)).  For a key example, see @(tsee
 use-trivial-ancestors-check).</p>

 <p>Another way to speed up system functions can be by using @(see
 memoization).  Here is an example from
 @('books/projects/stateman/stateman22.lisp').</p>

 @({
 (memoize 'acl2::sublis-var1
          :condition '(and (null acl2::alist)
                           (consp acl2::form)
                           (eq (car acl2::form) 'HIDE)))
 })

 <p>See @(see memoized-prover-fns) for a convenient way to do such memoization
 that automatically clears memoization tables after each event.  (Also see
 @(see clear-memoize-table) and @(see clear-memoize-tables), and see @(see
 hons-wash) for another way to clean up after memoization.)  Comments in the
 book @('books/tools/memoize-prover-fns.lisp') note a reduction in proof time
 from 4200 seconds to 49 seconds for one example by memoizing some system
 functions.  Those comments also have some discussion about which system
 functions to consider memoizing.  Perhaps ACL2 users will contribute further
 documentation on which system functions to memoize for efficiency.</p>

 <p>The following may be helpful at the level of book certification, and are
 discussed in :doc certify-book-debug.</p>

 @({
 (set-serialize-character-system nil)
 (set-bad-lisp-consp-memoize nil)
 (set-inhibit-output-lst '(proof-tree event))
 })

 <h3>Programming efficiency</h3>

 <p>Ideas for efficient programming include the use of compilation for host
 Lisps (other than CCL and SBCL, which compile automatically); see @(see comp)
 and @(see set-compile-fns).  For @(see logic)-mode functions, verify @(see
 guard)s if feasible; otherwise consider using @(see program)-mode wrappers
 (see @(see program-wrapper)).  Consider writing recursive definitions using
 tail recursion when possible.  In some cases the use of hash cons,
 memoization, or fast alists may reduce computation time dramatically; see
 @(see hons-and-memoization).  Single-threaded objects (see @(see stobj)),
 @(see arrays), @(see multiple-value) return, and @(tsee mbe) are helpful
 programming constructs provided by ACL2 for efficient execution.  Some
 built-in functions are constructed for efficiency; see for example @(tsee
 cons-with-hint) to reduce consing and @(see read-file-into-string) for
 obtaining the contents of a file quickly.</p>

 <p>You might find @(tsee type) @(see declaration)s to be useful.  In
 particular, if your host Lisp is GCL then the use of the declaration
 @('(signed-byte 64)'), or any stronger declaration (e.g., @('(unsigned-byte
 63)'), @('(signed-byte 12)'), or @('(integer 0 100)')), can provide dramatic
 performance improvements in compiled code.  You can peruse that code using
 @(see disassemble$).</p>

 <p>Of course, if a programming technique or construct is useful for efficient
 execution in Common Lisp and it is supported by ACL2, then it is useful for
 efficient execution in ACL2.  In particular, consider using @(tsee type) @(see
 declaration)s for numbers in place of @(tsee xargs) @(':')@(tsee guard).</p>

 <h3>Miscellaneous efficiency ideas</h3>

 <p>The use of @(tsee make-event) can sometimes reduce computation time; see
 for example @(see using-tables-efficiently) and @(see defconsts).</p>

 <p>You can @(see profile) functions to see where time is being spent during
 proofs or when computing with user-defined functions.  Sometimes it is even
 useful to profile virtually all ACL2 source functions, or even virtually all
 user-defined functions.  That can be done as follows &mdash; also see @(see
 profile-acl2) and @(see profile-all) &mdash; but note that when the problem is
 slow proofs, then since the results will display time spent in various ACL2
 prover routines, those results might not be helpful to most users.</p>

 @({
 (include-book "centaur/memoize/old/profile" :dir :system)
 (profile-acl2) ; or, (profile-all) to include user-defined functions
 [[Then run a slow form.]]
 (memsum) ; shows where time is spent
 })

 <p>For computations and proofs that may benefit from parallel computation, you
 could build the variant ACL2(p) of ACL2.  See @(see parallelism).</p>

 ")

(defxdoc eighth
  :parents (nth acl2-built-ins)
  :short "Eighth member of the list"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc elim
  :parents (rule-classes)
  :short "Make a destructor elimination rule"
  :long "<p>See @(see rule-classes) for a general discussion of rule classes,
 including how they are used to build rules from formulas and a discussion of
 the various keywords in a rule class description.</p>

 <p>The following example of an @(':elim') rule is an important one, and is
 built into ACL2.</p>

 @({
  (defaxiom car-cdr-elim
    (implies (consp x)
             (equal (cons (car x) (cdr x)) x))
    :rule-classes :elim)
 })

 <p>The class of @(':elim') rules is fundamentally quite different from the
 more common class of @(':')@(tsee rewrite) rules.  Briefly put, a
 @(':rewrite') rule replaces instances of its left-hand side with corresponding
 instances of its right-hand side.  But an @(':elim') rule, on the other hand,
 has the effect of generalizing so-called ``destructor'' function applications
 to variables.  In essence, applicability of a @(':rewrite') rule is based on
 matching its left-hand side, while applicability of an @(':elim') rule is
 based on the presence of at least one destructor term.</p>

 <p>For example, a conjecture about @('(car x)') and @('(cdr x)') can be
 replaced by a conjecture about new variables @('x1') and @('x2'), as shown in
 the following example.  (Run the command @(':mini-proveall') and search for
 @('CAR-CDR-ELIM') to see the full proof containing this excerpt.)</p>

 @({
  Subgoal *1/1'
  (IMPLIES (AND (CONSP X)
                (TRUE-LISTP (REV (CDR X))))
           (TRUE-LISTP (APP (REV (CDR X)) (LIST (CAR X))))).

  The destructor terms (CAR X) and (CDR X) can be eliminated by using
  CAR-CDR-ELIM to replace X by (CONS X1 X2), (CAR X) by X1 and (CDR X)
  by X2.  This produces the following goal.

  Subgoal *1/1''
  (IMPLIES (AND (CONSP (CONS X1 X2))
                (TRUE-LISTP (REV X2)))
           (TRUE-LISTP (APP (REV X2) (LIST X1)))).

  This simplifies, using primitive type reasoning, to

  Subgoal *1/1'''
  (IMPLIES (TRUE-LISTP (REV X2))
           (TRUE-LISTP (APP (REV X2) (LIST X1)))).
 })

 <p>The resulting conjecture is often simpler and hence more amenable to
 proof.</p>

 <p>The application of an @(':elim') rule thus replaces a variable by a term
 that contains applications of so-called ``destructor'' functions to that
 variable.  The example above is typical: the variable @('x') is replaced by
 the term @('(cons (car x) (cdr x))'), which applies a so-called
 ``constructor'' function, @(tsee cons), to applications @('(car x)') and
 @('(cdr x)') of destructor functions @(tsee car) and @(tsee cdr) to that same
 variable, @('x').  But that is only part of the story.  ACL2 then generalizes
 the destructor applications @('(car x)') and @('(cdr x)') to new variables
 @('x1') and @('x2'), respectively, and ultimately the result is a simpler
 conjecture.</p>

 <p>More generally, the application of an @(':elim') rule replaces a variable
 by a term containing applications of destructors; there need not be a
 clear-cut notion of ``constructor.''  But the situation described above is
 typical, and we will focus on it, giving full details when we introduce the
 ``General Form'' below.</p>

 <p>Notice that the situation can be complicated a bit by a rule's hypotheses.
 For example, the replacement specified by the rule @('car-cdr-elim') (shown
 near the beginning of this discussion) is only valid if the variable being
 replaced is a cons structure.  Thus, when ACL2 applies @('car-cdr-elim') to
 replace a variable @('v'), it will split into two cases: one case in which
 @('(consp v)') is true, in which @('v') is replaced by @('(cons (car v) (cdr
 v))') and then @('(car v)') and @('(cdr v)') are generalized to new variables;
 and one case in which @('(consp v)') is false.  In practice, @('(consp v)') is
 often provable, perhaps even literally present as a hypotheses; then of course
 there is no need to introduce the second case.  That is why there is no such
 second case in the example above.</p>

 <p>You might find @(':elim') rules to be useful whenever you have in mind a
 data type that can be built up from its fields with a ``constructor'' function
 and whose fields can be accessed by corresponding ``destructor'' functions.
 So for example, if you have a ``house'' data structure that represents a house
 in terms of its address, price, and color, you might have a rule like the
 following.</p>

 @({
  Example:
  (implies (house-p x)
           (equal (make-house (address x)
                              (price x)
                              (color x))
                  x))
 })

 <p>The application of such a rule is entirely analogous to the application of
 the rule @('car-cdr-elim') discussed above.  We discuss such rules and their
 application more carefully below.</p>

 @({
  General Form:
  (implies hyp (equiv lhs x))
 })

 <p>where @('equiv') is a known equivalence relation (see @(see defequiv));
 @('x') is a variable symbol; and @('lhs') contains one or more terms (called
 ``destructor terms'') of the form @('(fn v1 ... vn)'), where @('fn') is a
 function symbol and the @('vi') are distinct variable symbols, @('v1'), ...,
 @('vn') include all the variable symbols in the formula, no @('fn') occurs in
 @('lhs') in more than one destructor term, and all occurrences of @('x') in
 @('lhs') are inside destructor terms.</p>

 <p>An @(':elim') rule is available for a given destructor function (in the
 manner described below) when it is the most recently added @(see enable)d
 @(':elim') rule for that function.</p>

 <p>To use an @(':elim') rule, the theorem prover waits until a conjecture has
 been maximally simplified.  It then searches for an instance of some
 destructor term @('(fn v1 ... vn)') in the conjecture, where the instance for
 @('x') is some variable symbol, @('vi'), and every occurrence of @('vi')
 outside the destructor terms is in an @('equiv')-hittable position.  If such
 an instance is found, then the theorem prover instantiates the @(':elim')
 formula as indicated by the destructor term matched; splits the conjecture
 into two goals, according to whether the instantiated hypothesis, @('hyp'),
 holds; and in the case that it does hold, generalizes all the instantiated
 destructor terms in the conjecture to new variables and then replaces @('vi')
 in the conjecture by the generalized instantiated @('lhs').  An occurrence of
 @('vi') is ``@('equiv')-hittable'' if sufficient congruence rules (see @(see
 defcong)) have been proved to establish that the propositional value of the
 @(see clause) is not altered by replacing that occurrence of @('vi') by some
 @('equiv')-equivalent term.</p>

 <p>If an @(':elim') rule is not applied when you think it should have been,
 and the rule uses an equivalence relation, @('equiv'), other than @('equal'),
 it is most likely that there is an occurrence of the variable that is not
 @('equiv')-hittable.  Easy occurrences to overlook are those in the governing
 hypotheses.  If you see an unjustified occurrence of the variable, you must
 prove the appropriate congruence rule to allow the @(':elim') to fire.</p>

 <p>Further examples of how ACL2 @(':elim') rules are used may be found in the
 corresponding discussion of ``Elimination of Destructors'' for Nqthm, in
 Section 10.4 of A Computational Logic Handbook.</p>")

(defxdoc emacs
  :parents (acl2-tutorial)
  :short "Emacs support for ACL2"
  :long "<p>Many successful users of ACL2 take advantage of the Emacs editor,
 for example by running ACL2 in an Emacs shell buffer.  If you do so, then you
 may wish to load the distributed file @('emacs-acl2.el') from one of two
 directories under the main ACL2 directory: @('books/emacs/') if you use a
 recent version of Emacs, or @('emacs/') if you use Emacs 24.  An easy way to
 arrange this is to put the load form into your @('.emacs') file; here,
 @('DIR') denotes your main ACL2 directory.</p>

 @({
 (load "DIR/books/emacs/emacs-acl2.el") ; for recent Emacs versions
 })

 <p><b>-OR-</b></p>

 @({
 (load "DIR/emacs/emacs-acl2.el") ; for Emacs 24
 })

 <p>The file begins with considerable comments describing what it offers.</p>

 <p>In particular, the above file provides the ACL2-Doc browser, a convenient
 tool for viewing, in Emacs, documentation for both the ACL2 system and the
 documented community books, as well as custom manuals.  See @(see
 ACL2-Doc).</p>

 <p>If you are not comfortable with Emacs, you may prefer to use an
 Eclipse-based interface; see @(see acl2-sedan).</p>")

(defxdoc embedded-event-form
  :parents (events)
  :short "Forms that may be embedded in other @(see events)"
  :long "@({
  Examples:
  (defun hd (x) (if (consp x) (car x) 0))
  (local (defthm lemma23 ...))
  (progn (defun fn1 ...)
         (local (defun fn2 ...))
         ...)

  General Form:
  An embedded event form is a term, x, such that:
 })

 <ul>

 <li>@('x') is a call of an event function other than @(tsee DEFPKG) (see
 @(see events) for a listing of the event functions);</li>

 <li>@('x') is a call of @(tsee ENCAPSULATE), @(tsee PROGN), @(tsee PROGN!),
 or @(tsee INCLUDE-BOOK);</li>

 <li>@('x') is of the form @('(LOCAL x1)') where @('x1') is an
 embedded event form;</li>

 <li>@('x') is of the form @('(MAKE-EVENT &)'), where @('&') is any term whose
 expansion is an embedded event (see @(see make-event));</li>

 <li>@('x') is of the form @('(SKIP-PROOFS x1)') where @('x1') is
 an embedded event form;</li>

 <li>@('x') is of the form @('(WITH-CBD str x1)'), where @('str') is a string
 and @('x1') is an embedded event form;</li>

 <li>@('x') is of the form @('(WITH-GUARD-CHECKING-EVENT c x1)') or
 @('(WITH-GUARD-CHECKING-EVENT (QUOTE c) form)'), where @('c') is a member of
 the list @(`*guard-checking-values*`) and @('x1') is an embedded event
 form;</li>

 <li>@('x') is of the form @('(WITH-OUTPUT ... x1)'),
 @('(WITH-PROVER-STEP-LIMIT ... x1 ...)'), or @('(WITH-PROVER-TIME-LIMIT
 ... x1)'), where @('x1') is an embedded event form;</li>

 <li>@('x') macroexpands to one of the forms above; or</li>

 <li>[intended only for the implementation] @('x') is @('(RECORD-EXPANSION x1
 x2)'), where @('x1') and @('x2') are embedded event forms.</li>

 </ul>

 <p>However, we add the following restrictions for @(tsee local) contexts.</p>

 <ul>

 <li>An embedded event form may not set the @(tsee acl2-defaults-table) when in
 the context of @(tsee local).  Thus for example, the form

 @({
  (local (table acl2-defaults-table :defun-mode :program))
 })

 is not an embedded event form, nor is the form @('(local (program))'),
 since the latter sets the @(tsee acl2-defaults-table) implicitly.  An example
 at the end of the discussion below illustrates why there is this
 restriction.</li>

 <li>A call of @(tsee defaxiom) is illegal in the context of @(tsee local).
 Without this restriction, one could locally assert a strong axiom like
 @('(equal t nil)') and then non-locally prove that formula, leaving you in an
 ACL2 logical @(see world) in which it appears that the formula is actually
 provable without such an axiom.</li>

 <li>A call of @(tsee add-include-book-dir!) or @(tsee
 delete-include-book-dir!) is illegal in the context of @(tsee local).  For an
 explanation, see @(see add-include-book-dir!).</li>

 </ul>

 <p>Only embedded event forms are allowed in a book after its initial @(tsee
 in-package) form.  See @(see books).  However, you may find that @(tsee
 make-event) allows you to get the effect you want for a form that is not an
 embedded event form.  For example, you can put the following into a book,
 which assigns the value 17 to @(tsee state) global variable @('x'):</p>

 @({
  (make-event (er-progn (assign x 17)
                        (value '(value-triple nil)))
              :check-expansion t)
 })

 <p>For another use of @('make-event') to create embedded event forms, see
 @(see make-event-example-3).</p>

 <p>When an embedded event is executed while @(tsee ld-skip-proofsp) is
 @(''')@(tsee include-book), those parts of it inside @(tsee local) forms are
 ignored.  Thus,</p>

 @({
     (progn (defun f1 () 1)
            (local (defun f2 () 2))
            (defun f3 () 3))
 })

 <p>will define @('f1'), @('f2'), and @('f3') when @(tsee ld-skip-proofsp) is
 @('nil') or @('t'), but will define only @('f1') and @('f3') when @(tsee
 ld-skip-proofsp) is @(''')@(tsee include-book).</p>

 <p><i>Discussion:</i></p>

 <p>@(tsee Encapsulate), @(tsee progn), and @(tsee include-book) place
 restrictions on the kinds of forms that may be processed.  These restrictions
 ensure that the non-local @(see events) are indeed admissible provided that
 the sequence of @(tsee local) and non-local @(see events) is admissible when
 proofs are done, i.e., when @('ld-skip-proofs') is @('nil').  But @(tsee
 progn!) places no such restrictions, hence is potentially dangerous and should
 be avoided unless you understand the ramifications; so it is illegal unless
 there is an active trust tag (see @(see defttag)).</p>

 <p>@(tsee Local) permits the hiding of an event or group of @(see events) in
 the sense that @(tsee local) @(see events) are processed when we are trying to
 establish the admissibility of a sequence of @(see events) embedded in @(tsee
 encapsulate) forms or in @(see books), but are ignored when we are
 constructing the @(see world) produced by assuming that sequence.  Thus, for
 example, a particularly ugly and inefficient @(':')@(tsee rewrite) rule might
 be made @(tsee local) to an @(see encapsulate) that ``exports'' a desirable
 theorem whose proof requires the ugly lemma.</p>

 <p>To see why we can't allow just anything as an embedded event, consider
 allowing the form</p>

 @({
  (if (ld-skip-proofsp state)
      (defun foo () 2)
      (defun foo () 1))
 })

 <p>followed by</p>

 @({
  (defthm foo-is-1 (equal (foo) 1)).
 })

 <p>When we process the @(see events) with @(tsee ld-skip-proofsp) is @('nil'),
 the second @(tsee defun) is executed and the @(tsee defthm) succeeds.  But
 when we process the @(see events) with @(tsee ld-skip-proofsp) @(''')@(tsee
 include-book), the second @(tsee defun) is executed, so that @('foo') no
 longer has the same definition it did when we proved @('foo-is-1').  Thus, an
 invalid formula is assumed when we process the @(tsee defthm) while skipping
 proofs.  Thus, the first form above is not a legal embedded event form.</p>

 <p>If you encounter a situation where these restrictions seem to prevent you
 from doing what you want to do, then you may find @('make-event') to be
 helpful.  See @(see make-event).</p>

 <p>@(tsee Defpkg) is not allowed because it affects how things are read after
 it is executed.  But all the forms embedded in an event are read before any
 are executed.  That is,</p>

 @({
  (encapsulate nil
               (defpkg "MY-PKG" nil)
               (defun foo () 'my-pkg::bar))
 })

 <p>makes no sense since @('my-pkg::bar') must have been read before the @(tsee
 defpkg) for @('"MY-PKG"') was executed.</p>

 <p>Finally, let us elaborate on the restriction mentioned earlier related to
 the @(tsee acl2-defaults-table).  Consider the following form.</p>

 @({
  (encapsulate
   ()
   (local (program))
   (defun foo (x)
     (if (equal 0 x)
         0
       (1+ (foo (- x))))))
 })

 <p>See @(see local-incompatibility) for a discussion of how @(tsee
 encapsulate) processes event forms.  Briefly, on the first pass through the
 @(see events) the definition of @('foo') will be accepted in @(tsee defun)
 mode @(':')@(tsee program), and hence accepted.  But on the second pass the
 form @('(local (program))') is skipped because it is marked as @(tsee local),
 and hence @('foo') is accepted in @(tsee defun) mode @(':')@(tsee logic).
 Yet, no proof has been performed in order to admit @('foo'), and in fact, it
 is not hard to prove a contradiction from this definition!</p>")

(defxdoc enable
  :parents (theories theory-functions)
  :short "Adds names to current theory"
  :long "@({
  Example:
  (enable fact (:e fact) associativity-of-app)

  General Form:
  (enable name1 name2 ... namek)
 })

 <p>where each @('namei') is a runic designator; see @(see theories).  The
 result is the theory that contains all the names in the current theory plus
 those listed.  Note that this is merely a function that returns a theory.  The
 result is generally a very long list of @(see rune)s and you will probably
 regret printing it.</p>

 <p>For related utilities, see @(see disable) and see @(see e/d).</p>

 <p>The standard way to ``enable'' a fixed set of names, is as follows; see
 @(see hints) and see @(see in-theory).</p>

 @({
  :in-theory (enable name1 name2 ... namek)  ; in a hint
  (in-theory (enable name1 name2 ... namek)) ; as an event
  (local ; often desirable, to avoid exporting from the current context
   (in-theory (enable name1 name2 ... namek)))
 })

 <p>Note that all the names are implicitly quoted.  If you wish to enable a
 computed list of names, @('lst'), use the theory expression @('(union-theories
 (current-theory :here) lst)').</p>

 <p>To see the runes currently disabled that are among those created when a
 function symbol @('FN') is introduced, evaluate @('(disabledp 'FN)').</p>")

(defxdoc enable-forcing
  :parents (force)
  :short "To allow forced case splits"
  :long "@({
  General Form:
  ACL2 !>:enable-forcing    ; allowed forced case splits
 })

 <p>See @(see force) and see @(see case-split) for a discussion of forced case
 splits, which are turned back on by this command.  See @(see disable-forcing)
 for an example showing how to turn off forced case splits.</p>

 <p>@('Enable-forcing') is actually a macro that @(see enable)s the @(see
 executable-counterpart) of the function symbol @('force'); see @(see force).
 When you want to use @(see hints) to turn on forced case splits, use a form
 such as one of the following (these are equivalent).</p>

 @({
  :in-theory (enable (:executable-counterpart force))
  :in-theory (enable (force))
 })")

(defxdoc enable-immediate-force-modep
  :parents (force)
  :short "@(see force)d hypotheses are attacked immediately"
  :long "@({
  General Form:
  ACL2 !>:enable-immediate-force-modep
 })

 <p>This event causes ACL2 to attack @(see force)d hypotheses immediately
 instead of delaying them to the next forcing round.  See @(see
 immediate-force-modep).  Or for more basic information, first see @(see force)
 for a discussion of @(see force)d case splits.</p>

 <p>Enable-immediate-force-modep is a macro that @(see enable)s the @(see
 executable-counterpart) of the function symbol @(tsee immediate-force-modep).
 When you want to @(see enable) this mode in @(see hints), use a form such as
 one of the following (these are equivalent).</p>

 @({
  :in-theory (enable (:executable-counterpart immediate-force-modep))
  :in-theory (enable (immediate-force-modep))
 })")

(defxdoc encapsulate
  :parents (events)
  :short "Hide some @(see events) and/or constrain some functions"
  :long "<p>@('Encapsulate') provides a way to execute a sequence of @(see
 events) and then hide some of the resulting effects.  There are two kinds of
 encapsulations: ``trivial'' and ``non-trivial''.  We discuss these briefly
 before providing detailed @(see documentation).</p>

 <p>A trivial encapsulation is an event of the following form.</p>

 @({
  (encapsulate
   () ; nil here indicates "trivial"
   <event-1>
   ...
   <event-k>)
 })

 <p>We use the term ``sub-events'' to refer to @('<event-1>') through
 @('<event-k>').  Each sub-event @('<event-i>') may be ``@(see local)'', that
 is, of the form @('(local <event-i'>)'); the other sub-events are called
 ``non-local''.  When this @('encapsulate') form is submitted to ACL2, it is
 processed in two passes.  On the first pass, each sub-event is printed (by
 default) and processed in sequence; admission of the @('encapsulate') fails if
 any @('<event-i>') fails to be admitted.  Then a second pass is made after
 rolling back the logical @(see world) to what it was just before executing the
 @('encapsulate') form.  In the second pass, only the non-@(see local) forms
 @('<event-i>') are evaluated, again in order, and proofs are skipped.</p>

 <p>For example, the following trivial encapsulation exports a single event,
 @('member-equal-reverse').  The lemma @('member-revappend') is used (as a
 @(see rewrite) rule) to prove @('member-equal-reverse') on the first pass, but
 since @('member-revappend') is @(see local), it is ignored on the second
 (final) pass.</p>

 @({
  (encapsulate
   ()

   (local
    (defthm member-revappend
      (iff (member-equal a (revappend x y))
           (or (member-equal a x)
               (member-equal a y)))
      :hints (("Goal" :induct (revappend x y)))))

   (defthm member-equal-reverse
     (iff (member-equal a (reverse x))
          (member-equal a x))))
 })

 <p>Of course, one might prefer to prove these @(see events) at the top level,
 rather than within an encapsulation; but the point here is to illustrate that
 you can have @(see local) @(see events) that do not become part of the logical
 @(see world).  (Such a capability is also provided at the level of @(see
 books); in particular, see @(see include-book).)</p>

 <p>Note that trivial encapsulates must introduce at least one sub-event, or
 else they are treated as no-ops, with no effect on the logical @(see world).
 Consider the following example.</p>

 @({
 ACL2 !>(encapsulate nil (local (defun f (x) x)))

 To verify that the encapsulated event correctly extends the current
 theory we will evaluate it.  The theory thus constructed is only ephemeral.

 Encapsulated Event:


 ACL2 !>>(LOCAL (DEFUN F (X) X))

 Since F is non-recursive, its admission is trivial.  We observe that
 the type of F is described by the theorem (EQUAL (F X) X).

 Summary
 Form:  ( DEFUN F ...)
 Rules: NIL
 Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
 F

 End of Encapsulated Event.

 ACL2 Observation in ( ENCAPSULATE NIL (LOCAL ...) ...):  The submitted
 encapsulate event has created no new ACL2 events, and thus is leaving
 the ACL2 logical world unchanged.  See :DOC encapsulate.

 Summary
 Form:  ( ENCAPSULATE NIL (LOCAL ...) ...)
 Rules: NIL
 Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
  :EMPTY-ENCAPSULATE
 ACL2 !>
 })

 <p>After the above evaluation, we are left in the @(see world) with which we
 began.  For example, if you evaluate the above form in the initial ACL2 world,
 you can see the following both before and after that evaluation.</p>

 @({
 ACL2 !>:pbt 0
            0:x(EXIT-BOOT-STRAP-MODE)
 ACL2 !>
 })

 <p>On the other hand, non-trivial encapsulations provide a way to introduce
 axioms about new function symbols, without introducing inconsistency and
 without introducing complete definitions.  The following example illustrates
 how that works.</p>

 @({
  (encapsulate

  ; The following list has a single signature, introducing a function foo of
  ; one argument that returns one value.  (The list is non-empty, so we call
  ; this a "non-trivial" encapsulation.)
   ( ((foo *) => *) )

  ; Introduce a ``witness'' (example) for foo, marked as local so that
  ; it is not exported:
   (local (defun foo (x) x))

  ; Introduce a non-local property to be exported:
   (defthm foo-preserves-consp
     (implies (consp x)
              (consp (foo x))))
  )
 })

 <p>The form above introduces a new function symbol, @('foo'), with the
 indicated property and no definition.  In fact, the output from ACL2 concludes
 as follows.</p>

 @({
  The following constraint is associated with the function FOO:

  (IMPLIES (CONSP X) (CONSP (FOO X)))
 })

 <p>To understand this example, we consider how non-trivial encapsulations are
 processed.  The same two passes are made as for trivial encapsulations, and
 the (@(see local)) definition of @('foo') is ignored on the second pass, and
 hence does not appear in the resulting ACL2 logical @(see world).  But before
 the second pass, each @(see signature) is stored in the @(see world).  Thus,
 when the theorem @('foo-preserves-consp') is encountered in the second pass,
 @('foo') is a known function symbol with the indicated signature.</p>

 <p>If any event fails while evaluating a call of @('encapsulate'), the entire
 @('encapsulate') call is deemed to have failed, and the logical @(see world)
 is rolled back to what it was immediately before the @('encapsulate')
 call.</p>

 <p>We now provide detailed documentation.  But discussion of redundancy for
 @('encapsulate') events may be found elsewhere; see @(see
 redundant-encapsulate).</p>

 @({
  Other Examples:
  (encapsulate (((an-element *) => *))

  ; The list of signatures above could also be written
  ;            ((an-element (lst) t))

    (local (defun an-element (lst)
             (if (consp lst) (car lst) nil)))
    (local (defthm member-equal-car
              (implies (and lst (true-listp lst))
                       (member-equal (car lst) lst))))
    (defthm thm1
       (implies (null lst) (null (an-element lst))))
    (defthm thm2
       (implies (and (true-listp lst)
                     (not (null lst)))
                (member-equal (an-element lst) lst))))

  (encapsulate
   () ; empty signature: no constrained functions indicated

   (local (defthm hack
            (implies (and (syntaxp (quotep x))
                          (syntaxp (quotep y)))
                     (equal (+ x y z)
                            (+ (+ x y) z)))))

   (defthm nthcdr-add1-conditional
     (implies (not (zp (1+ n)))
              (equal (nthcdr (1+ n) x)
                     (nthcdr n (cdr x))))))

  General Form:
  (encapsulate (signature ... signature)
    ev1
    ...
    evn)
 })

 <p>where each @(tsee signature) is a well-formed signature, each
 @('signature') describes a different function symbol, and each @('evi') is an
 embedded event form (see @(see embedded-event-form)).  Also see @(see
 signature), in particular for a discussion of how a signature can assign a
 @(see guard) to a function symbol.  There must be at least one @('evi').  The
 @('evi') inside @(tsee local) special forms are called ``local'' @(see events)
 below.  @(see Events) that are not @(tsee local) are sometimes said to be
 ``exported'' by the encapsulation.  We make the further restriction that no
 @(tsee defaxiom) event may be introduced in the scope of an @('encapsulate')
 (not even by @('encapsulate') or @(tsee include-book) events that are among
 the @('evi')).  Furthermore, no non-@(tsee local) @(tsee include-book) event
 is permitted in the scope of any @('encapsulate') with a non-empty list of
 signatures.</p>

 <p>To be well-formed, an @('encapsulate') event must have the properties that
 each event in the body (including the @(tsee local) ones) can be successfully
 executed in sequence and that in the resulting theory, each function mentioned
 among the @(see signature)s was introduced via a @(tsee local) event and has
 the @(see signature) listed.  (A utility is provided to assist in debugging
 failures of such execution; see @(see redo-flat).)  In addition, the body may
 contain no ``local incompatibilities'' which, roughly stated, means that the
 @(see events) that are not @(tsee local) must not syntactically require
 symbols defined by @(tsee local) @(tsee events), except for the functions
 listed in the @(see signature)s.  See @(see local-incompatibility).  Finally,
 no non-@(tsee local) recursive definition in the body may involve in its
 suggested induction scheme any function symbol listed among the @(see
 signature)s.  See @(see subversive-recursions).</p>

 <p>Observe that if the @(see signature)s list is empty, the resulting
 ``trivial'' @('encapsulate') may still be useful for deriving theorems to be
 exported whose proofs require lemmas you prefer to hide (i.e., made @(tsee
 local)).  Whether trivial or not (i.e., whether the signature is empty or
 not), @('encapsulate') exports the results of evaluating its non-@(tsee local)
 @(see events), but its @(tsee local) @(see events) are ignored for the
 resulting logical @(see world).</p>

 <p>The result of a non-trivial @('encapsulate') event is an extension of the
 logic in which, roughly speaking, the functions listed in the @(see
 signature)s are constrained to have the @(see signature)s listed and to
 satisfy the non-@(tsee local) theorems proved about them.  In fact, other
 functions introduced in the @('encapsulate') event may be considered to have
 ``@(see constraint)s'' as well.  (See @(see constraint) for details, which are
 only relevant to functional instantiation.)  Since the @(see constraint)s were
 all theorems in the ``ephemeral'' or ``local'' theory, we are assured that the
 extension produced by @('encapsulate') is sound.  In essence, the @(tsee
 local) definitions of the constrained functions are just ``witness functions''
 that establish the consistency of the @(see constraint)s.  Because those
 definitions are @(tsee local), they are not present in the theory produced by
 encapsulation.  After a non-trivial @('encapsulate') event is admitted,
 theorems about the constrained function symbols may then be proved &mdash;
 theorems whose proofs necessarily employ only the @(see constraint)s.  Thus,
 those theorems may be later functionally instantiated, as with the
 @(':functional-instance') lemma instance (see @(see lemma-instance)), to
 derive analogous theorems about different functions, provided the constraints
 (see @(see constraint)) can be proved about the new functions.</p>

 <p>The @(see default-defun-mode) for the first event in an encapsulation is
 the default @(see defun-mode) ``outside'' the encapsulation.  But since @(see
 events) changing the @(see defun-mode) are permitted within the body of an
 @('encapsulate'), the default @(see defun-mode) may be changed.  However,
 @(see defun-mode) changes occurring within the body of the @('encapsulate')
 are not exported.  In particular, the @(tsee acl2-defaults-table) after an
 @('encapsulate') is always the same as it was before the @('encapsulate'),
 even though the @('encapsulate') body might contain @(see defun-mode) changing
 @(see events), @(':')@(tsee program) and @(':')@(tsee logic).  See @(see
 defun-mode).  More generally, after execution of an @('encapsulate') event,
 the value of @(tsee acl2-defaults-table) is restored to what it was
 immediately before that event was executed.  See @(see
 acl2-defaults-table).</p>

 <p>We make some remarks on @(see guard)s and evaluation.  Calls of functions
 introduced in the @(see signature)s list cannot be evaluated in the ACL2
 read-eval-print loop.  See @(see defattach) for a way to overcome this
 limitation.  Moreover, any @(':')@(tsee guard) supplied in the signature is
 automatically associated in the @(see world) with its corresponding function
 symbol, with no requirement beyond what is required for a legal @(see
 signature) other than that all of the guard's function symbols are in
 @(':')@(tsee logic) mode with their @(see guard)s verified.  In particular,
 there need not be any relationship between a guard in a signature and the
 guard in a @('local') witness function.  Finally, note that for functions
 introduced non-@(see local)ly inside a non-trivial @('encapsulate') event,
 @(see guard) verification is illegal unless ACL2 determines that the proof
 obligations hold outside the @(tsee encapsulate) event as well.</p>

 @({
  (encapsulate
   ((f (x) t))
   (local (defun f (x) (declare (xargs :guard t)) (consp x)))
   ;; ERROR!
   (defun g (x)
     (declare (xargs :guard (f x)))
     (car x)))
 })

 <p>The order of the @(see events) in the vicinity of an @('encapsulate') is
 confusing.  We discuss it in some detail here because when logical names are
 being used with theory functions to compute sets of rules, it is sometimes
 important to know the order in which @(see events) were executed.  (See @(see
 logical-name) and see @(see theory-functions).)  What, for example, is the set
 of function names extant in the middle of an encapsulation?</p>

 <p>If the most recent event is @('previous') and then you execute an
 @('encapsulate') constraining @('an-element') with two non-@(tsee local) @(see
 events) in its body, @('thm1') and @('thm2'), then the order of the @(see
 events) after the encapsulation is (reading chronologically forward):
 @('previous'), @('thm1'), @('thm2'), @('an-element') (the @('encapsulate')
 itself).  Actually, between @('previous') and @('thm1') certain extensions
 were made to the @(see world) by the superior @('encapsulate'), to permit
 @('an-element') to be used as a function symbol in @('thm1').</p>

 <p>Remark on return value.  As with all @(see events), a call of
 @('encapsulate') returns an @(see error-triple), @('(mv erp val state)'),
 where @('erp') is @('nil') when the event is redundant or is successfully
 admitted.  When @('erp') is @('nil'), the value @('val'), which is typically
 printed after a space, is determined as follows.</p>

 <ul>

 <li>If the @('encapsulate') event is @(see redundant), then @('val') is
 @(':redundant').</li>

 <li>Otherwise, if no new events are introduced, then @('val') is
 @(':empty-encapsulate').</li>

 <li>Otherwise, if the last sub-event in the final pass of the @('encapsulate')
 form evaluates to @('(mv nil '(:return-value x)')) for some @('x'), @('val')
 is @('x').  Note that this can be accomplished by placing the form
 @('(value-triple '(:return-value x) :on-skip-proofs t)') as the final form in
 the @('encapsulate'), but since proofs are skipped during that pass, the
 argument @(':on-skip-proofs t') is necessary for @('val') to be @('x').</li>

 <li>Otherwise, if the list of @(see signature)s is @('nil') then @('val') is
 @('t').</li>

 <li>Otherwise, if there is a single signature introducing the function symbol,
 @('fn'), then @('val') is @('fn').</li>

 <li>Otherwise, @('val') is the list of function symbols introduced in the list
 of signatures.</li>

 </ul>

 <p>Remark on implicit @(see constraint)s (unknown-constraints).  See @(see
 partial-encapsulate) for a related utility that allows some of the constraints
 to be unspecified.  This is an advanced capability that is useful when one
 installs special-purpose code, possibly in raw Lisp, using a trust tag (see
 @(see defttag)).</p>

 <p>Remark for ACL2(r) (see @(see real)).  For ACL2(r), @(tsee encapsulate) can
 be used to introduce classical and non-classical functions, as determined by
 the signatures; see @(see signature).  Those marked as classical (respectively
 non-classical) must have classical (respectively, non-classical) @(tsee local)
 witness functions.  A related requirement applies to functional instantiation;
 see @(see lemma-instance).</p>")

(defxdoc endp
  :parents (lists acl2-built-ins)
  :short "Recognizer for empty lists"
  :long "<p>In the ACL2 logic, @('(endp x)') is the same as @('(atom x)').  See
 @(see atom).</p>

 <p>Unlike @(tsee atom), the @(see guard) for @('endp') requires that @('x') is
 a @(tsee cons) pair or is @('nil').  Thus, @('endp') is typically used as a
 termination test for functions that recur on a @(tsee true-listp) argument.
 See @(see guard) for general information about @(see guard)s.</p>

 <p>@('Endp') is a Common Lisp function.  See any Common Lisp documentation for
 more information.</p>

 @(def endp)")

(defxdoc enter-boot-strap-mode
  :parents (history)
  :short "The first millisecond of the Big Bang"
  :long "<p>ACL2 functions, e.g., @(tsee if), that show
 @('enter-boot-strap-mode') as their defining @(see command) are in fact @(see
 primitive)s.  It is impossible for the system to display defining axioms about
 these symbols.</p>

 <p>@('Enter-boot-strap-mode') is a Common Lisp function but not an ACL2
 function.  It magically creates from @('nil') an ACL2 property list @(see
 world) that lets us start the boot-strapping process.  That is, once
 @('enter-boot-strap-mode') has created its @(see world), it is possible to
 process the @(tsee defconst)s, @(tsee defun)s, and @(tsee defaxiom)s,
 necessary to bring up the rest of the system.  Before that @(see world) is
 created, the attempt by ACL2 even to translate a @(tsee defun) form, say,
 would produce an error because @(tsee defun) is undefined.</p>

 <p>Several ACL2 functions show @('enter-boot-strap-mode') as their defining
 @(see command).  Among them are @(tsee if), @(tsee cons), @(tsee car), and
 @(tsee cdr).  These functions are characterized by axioms rather than
 definitional equations &mdash; axioms that in most cases are built into our
 code and hence do not have any explicit representation among the rules and
 formulas in the system.</p>")

(defxdoc eq
  :parents (equal equality-variants acl2-built-ins)
  :short "Equality of symbols"
  :long "<p>@('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 @(tsee equal) in the ACL2
 logic.</p>

 <p>@('Eq') is a Common Lisp function.  In order to ensure conformance with
 Common Lisp, the ACL2 @(see 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 @(tsee
 equal) to @('y').  Thus, the ACL2 user should think of @('eq') as nothing
 besides a fast means for checking @(tsee 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.</p>

 @(def eq)")

(defxdoc eql
  :parents (equal equality-variants acl2-built-ins)
  :short "Test equality (of two numbers, symbols, or @(see characters))"
  :long "<p>@('(eql x y)') is logically equivalent to @('(equal x y)').</p>

 <p>Unlike @(tsee equal), @('eql') has a @(see guard) requiring at least one of
 its arguments to be a number, a symbol, or a character.  Generally, @('eql')
 is executed more efficiently than @(tsee equal).</p>

 <p>For a discussion of the various ways to test against 0, See @(see
 zero-test-idioms).</p>

 <p>@('Eql') is a Common Lisp function.  See any Common Lisp documentation for
 more information.</p>

 @(def eql)")

(defxdoc eqlable-alistp
  :parents (alists acl2-built-ins)
  :short "Recognizer for a true list of pairs whose @(tsee car)s are suitable for @(tsee eql)"
  :long "<p>The predicate @('eqlable-alistp') tests whether its argument is a
 @(tsee true-listp) of @(tsee consp) objects whose @(tsee car)s all satisfy
 @(tsee eqlablep).</p>

 @(def eqlable-alistp)")

(defxdoc eqlable-listp
  :parents (eqlablep equal lists acl2-built-ins)
  :short "Recognizer for a true list of objects each suitable for @(tsee eql)"
  :long "<p>The predicate @('eqlable-listp') tests whether its argument is a
 @(tsee true-listp) of objects satisfying @(tsee eqlablep).</p>

 @(def eqlable-listp)")

(defxdoc eqlablep
  :parents (equal acl2-built-ins)
  :short "The @(see guard) for the function @(tsee eql)"
  :long "<p>The predicate @('eqlablep') tests whether its argument is suitable
 for @(tsee 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.</p>

 @(def eqlablep)")

(defxdoc equal
  :parents (basics acl2-built-ins)
  :short "True equality"
  :long "<p>@('(equal x y)') is equal to @('t') or @('nil'), according to
 whether or not @('x') and @('y') are the same value.</p>

 <p>For a discussion of the various idioms for testing against 0, See @(see
 zero-test-idioms).</p>")

(defxdoc equality-variants
  :parents (programming)
  :short "Versions of a function using different equality tests"
  :long "<p>The ACL2 environment includes not only a logic but also a
 programming language, which is based on Common Lisp.  Execution efficiency may
 be increased by using fast equality tests: @(tsee eq) for symbols and @(tsee
 eql) for numbers, symbols, and characters (see @(see eqlablep)).  Several
 list-processing functions built into ACL2 thus have three variants, depending
 on whether the equality function used is @(tsee eq), @(tsee eql), or @(tsee
 equal); a list is provided below.  ACL2 has taken measures to ensure that one
 can reason about a single logical function even when one uses these different
 variants.</p>

 <p>Consider for example the case of list membership.  Common Lisp provides a
 utility for this purposes, @(tsee member), which can take a @(':TEST') keyword
 argument, default @(tsee eql).  So for example, one might write</p>

 @({
  (member a x :TEST 'eq)
 })

 <p>if either @('a') is a symbol or @('x') is a list of symbols, so that the
 fastest equality test (@(tsee eq)) may be used when comparing @('a') to
 successive elements of the list, @('x').  One might elsewhere write @('(member
 b (foo y))'), which is equivalent to @('(member b (foo y) :TEST 'eql)'), for
 example if @('b') is a number.  If one wants to reason about both @('(member a
 x :TEST 'eq)') and @('(member b y)'), it might be helpful for both calls of
 @('member') to be the same logically, even though Common Lisp will execute
 them differently (using @(tsee eq) or @(tsee eql), respectively).  ACL2
 arranges that in fact, both references to @(tsee member) generate calls of
 @(tsee member-equal) in the theorem prover.</p>

 <p>In fact, since @(tsee member) can take the optional @(':TEST') keyword
 argument, then in ACL2 it must be defined as a macro, not a function (see
 @(see defun)).  ACL2 arranges that a call of @('member') generates a
 corresponding call of the function @(tsee member-equal), regardless of the
 value of @('TEST'), in a manner that produces @(tsee member-equal) in prover
 output.  More generally, you can expect ACL2 to treat your use of @(tsee
 member) as though you had written @(tsee member-equal), for example in the way
 it stores @(tsee rewrite) rules and other kinds of rules as well (see @(see
 rule-classes)).  We say little here about how this is all arranged by ACL2,
 other than to mention that @(tsee mbe) is utilized (so, you might see mention
 in proof logs) of the function @(tsee return-last) that implements @(tsee
 mbe).  Such details, which involve a notion of ``macro alias'' and probably
 can be ignored by most users, may be found elsewhere; see @(see
 equality-variants-details).</p>

 <p>As a convenience to the user, the macro @('member-eq') is provided that
 expands to a corresponding call of @('member') with @(':TEST 'eq'), as
 follows.</p>

 @({
  ACL2 !>:trans1 (member-eq (foo x) (bar y))
   (MEMBER (FOO X) (BAR Y) :TEST 'EQ)
  ACL2 !>
 })

 <p>For efficiency we recommend using the @('-equal') equality variant, for
 example @(tsee member-equal) or @('(')@(tsee member)@(' ... :TEST 'equal)'),
 in certain contexts: @(tsee defmacro), @(tsee defpkg), @(tsee defconst), and
 @(tsee value-triple) forms.  However, the implementation of equality variants
 has been designed so that when defining a function, one may choose freely in a
 definition an equality variant of primitive @('F'), to get efficient execution
 but where subsequent reasoning is about @('F-equal').  For details about the
 above recommendation and for a discussion of the implementation, see @(see
 equality-variants-details).</p>

 <p>The following alphabetical list includes all primitives that have equality
 variants.  Each macro @('F') listed below takes an optional @(':TEST') keyword
 argument of @(''eq'), @(''eql'), or @(''equal'), where @(''eql') is the
 default.  For each such @('F'), a function @('F-equal') is defined such that
 for logical purposes (in particular theorem proving), each call of @('F')
 expands to a corresponding call of @('F-equal').  For convenience, a macro
 @('F-eq') is also defined, so that a call of @('F-eq') expands to a
 corresponding call of @('F') with @(':TEST 'eq').</p>

 <code>
 @(tsee add-to-set)
 @(tsee assoc)
 @(tsee intersection$) ; (see Note below)
 @(tsee intersectp)
 @(tsee member)
 @(tsee no-duplicatesp)
 @('position-ac')
 @(tsee position)
 @(tsee put-assoc)
 @(tsee rassoc)
 @(tsee remove)
 @(tsee remove-assoc)
 @(tsee remove-duplicates)
 @(tsee remove1)
 @(tsee remove1-assoc)
 @(tsee set-difference$) ; (see Note below)
 @(tsee subsetp)
 @(tsee union$) ; (see Note below)
 </code>

 <p>Note: Three of the macros above have names ending with the character,
 `@('$')': @(tsee intersection$), @(tsee set-difference$), and @(tsee union$).
 In each case there is a corresponding Common Lisp primitive without the
 trailing `@('$')': @('intersection'), @('set-difference'), and @('union').
 However, Common Lisp does not specify the order of elements in the list
 returned by those primitives, so ACL2 has its own.  Nevertheless, the only use
 of the trailing `@('$')' is to distinguish the primitives; associated
 functions and macros, for example @('union-eq') and @('intersection-equal'),
 do not include the `@('$')' character in their names.</p>

 <p>We conclude with a brief discussion of @(see guards).  The expansion of any
 of the above macros depends on the keyword argument, which generates a
 function call with a guard suitable for the equality test being used.
 Consider for example the call @('(member x lst :test 'eq)'), or equivalently,
 @('(member-eq x lst)').  Expanding these macros leads to a call of @(tsee
 mbe); you can see how that goes by using @(':')@(tsee trans1).  Ultimately,
 the guard being checked is that of the function @('member-eq-exec'), which is
 as follows.</p>

 @({
  (if (symbolp x)
      (true-listp lst)
    (symbol-listp lst))
 })

 <p>Care has been taken to ensure that this guard is checked during evaluation
 and also that it generates suitable proof obligations for guard verification
 (see @(see verify-guards)).  A guard violation might look something like
 this:</p>

 @({
   ACL2 !>(member-eq 3 '(4 5))


   ACL2 Error in TOP-LEVEL:  The guard for the function call
   (MEMBER-EQ-EXEC$GUARD-CHECK X LST), which is
   (IF (SYMBOLP X) (TRUE-LISTP LST) (SYMBOL-LISTP LST)), is violated by
   the arguments in the call (MEMBER-EQ-EXEC$GUARD-CHECK 3 '(4 5)).
   See :DOC set-guard-checking for information about suppressing this
   check with (set-guard-checking :none), as recommended for new users.
   To debug see :DOC print-gv, see :DOC trace, and see :DOC wet.

   ACL2 !>
 })

 <p>Above, @('member-eq-exec$guard-check') is a function generated as part of
 ACL2's expansion of @('member') with @(':test 'eq'), and this function symbol
 can be quite reasonably ignored.  The important thing is that it refers to the
 guard for @('member-eq-exec'), which as the name may suggest is intended to
 guard the execution of a call of @(tsee member-eq), or a call of @(tsee
 member) with @(':test 'eq').  The important part of the message above is the
 guard actually being violated: @('(IF (SYMBOLP X) (TRUE-LISTP
 LST) (SYMBOL-LISTP LST))').</p>")

(defxdoc equality-variants-details
  :parents (equality-variants)
  :short "Details about @(see equality-variants)"
  :long "<p>Here we present details about equality variants, none of which is
 likely to be important to the majority of ACL2 users.  Please see @(see
 equality-variants) for relevant background.</p>

 <p>We begin by presenting @(see events) that implement the equality variants
 for @(tsee member), as these illustrate the events introduced for all macros
 having equality variants.  The definition of @(tsee member), just below, calls
 the macro @('let-mbe'), which in turn is just an abbreviation for a
 combination of @(tsee let) and @(tsee mbe).  Here is a simplified version of
 the definition of this macro.  For relevant background, see @(tsee mbe).</p>

 @({
  (defmacro let-mbe (bindings &key logic exec)
    `(let ,bindings
       (mbe :logic ,logic
            :exec ,exec)))
 })

 <p>This use of @(tsee let) arranges that each argument of a call of
 @('member') is evaluated only once.</p>

 <p>The actual definition of the macro @('let-mbe') is a bit more complex, in
 order to guarantee that @(see guard)s are appropriately checked.  For purposes
 of this discussion we ignore this simplification.  (You can find the
 definition of @('let-mbe') in ACL2 source file @('axioms.lisp').)</p>

 <p>Consider the following definition from ACL2 source file @('axioms.lisp').
 Notice that it invokes the macro @('let-mbe'), discussed above.</p>

 @({
  (defmacro member (x l &key (test ''eql))
    (declare (xargs :guard (or (equal test ''eq)
                               (equal test ''eql)
                               (equal test ''equal))))
    (cond
     ((equal test ''eq)
      `(let-mbe ((x ,x) (l ,l))
                :logic (member-equal x l)
                :exec  (member-eq-exec x l)))
     ((equal test ''eql)
      `(let-mbe ((x ,x) (l ,l))
                :logic (member-equal x l)
                :exec  (member-eql-exec x l)))
     (t ; (equal test 'equal)
      `(member-equal ,x ,l))))
 })

 <p>Inspection of the definition above shows that every call of @(tsee member)
 expands to one that is logically equivalent to the corresponding call of
 @(tsee member-equal), which is defined as follows.</p>

 @({
  (defun member-equal (x lst)
    (declare (xargs :guard (true-listp lst)))
    (cond ((endp lst) nil)
          ((equal x (car lst)) lst)
          (t (member-equal x (cdr lst)))))
 })

 <p>The following two definitions model equality variants of @(tsee member) for
 tests @(tsee eq) and @(tsee eql), respectively.</p>

 @({
  (defun member-eq-exec (x lst)
    (declare (xargs :guard (if (symbolp x)
                               (true-listp lst)
                             (symbol-listp lst))))
    (cond ((endp lst) nil)
          ((eq x (car lst)) lst)
          (t (member-eq-exec x (cdr lst)))))

  (defun member-eql-exec (x lst)
    (declare (xargs :guard (if (eqlablep x)
                               (true-listp lst)
                             (eqlable-listp lst))))
    (cond ((endp lst) nil)
          ((eql x (car lst)) lst)
          (t (member-eql-exec x (cdr lst)))))
 })

 <p>At this point the user can write @('(member x y)') or @('(member-equal x
 y)') to call equality variants of @('member') with test @('eql') or
 @('equal'), respectively.  We thus provide the following macro for the @('eq')
 variant.</p>

 @({
  (defmacro member-eq (x lst)
    `(member ,x ,lst :test 'eq))
 })

 <p>@(see Guard) proof obligations generated by calls of @('member') will
 include those based on its use of @('mbe'), and are supported by the following
 two lemmas.</p>

 @({
  (defthm member-eq-exec-is-member-equal
    (equal (member-eq-exec x l)
           (member-equal x l)))

  (defthm member-eql-exec-is-member-equal
    (equal (member-eql-exec x l)
           (member-equal x l)))
 })

 <p>Finally, the following two events arrange that in certain contexts such as
 @(see theories) (including the use of @(tsee in-theory) in @(see events) and
 @(see hints)), @(tsee member-eq) and @(tsee member) are treated as references
 to @(tsee member-equal).</p>

 @({
  (add-macro-alias member-eq member-equal)
  (add-macro-alias member member-equal)
 })

 <p>Note however that these events do not affect printing of calls during
 proofs: calls of @('member') and @('member-eq') will be macroexpanded away,
 leaving you with calls of @('member-equal') that are displayed in proof
 output.  For a way to change this behavior, see @(tsee add-macro-fn).</p>

 <p>We conclude this topic by exploring the following recommendation made in
 the @(see documentation) for @(see equality-variants).</p>

 <blockquote><p>For efficiency we recommend using the @('-equal') equality
 variant, for example @(tsee member-equal) or @('(')@(tsee member)@(' ... :TEST
 'equal)'), in certain contexts: @(tsee defmacro), @(tsee defpkg), @(tsee
 defconst), and @(tsee value-triple) forms.</p></blockquote>

 <p>ACL2 relies on the underlying Common Lisp for evaluation.  It also
 processes events in the ACL2 logic.  In order to guarantee consistency of its
 logical and Common Lisp evaluations, ACL2 uses a ``safe mode'' to avoid
 ill-guarded calls.  In particular, consider the use of @(tsee mbe) in
 execution of a call of an equality variant of a primitive, @('F'), other than
 its @('F-equal') variant.  The @(tsee mbe) call discussed above requires a
 connection to be established between the @(':logic') and @(':exec') forms.
 For example, if @('F') is called with @(':TEST 'eql') (either explicitly or as
 the default), then ACL2 will call both @('F-eql-exec') and @('F-equal'), and
 check that the two results are equal.</p>

 <p>The following partial log illustrates the point above.  We define a macro
 that calls @(tsee member), and when a call of this macro is expanded during
 processing of a subsequent definition, we see that two membership functions
 are called on the same arguments.</p>

 @({
  ACL2 !>(defmacro mac (lst)
           (list 'quote (and (true-listp lst)
                             (member 'c lst :test 'eq))))

  Summary
  Form:  ( DEFMACRO MAC ...)
  Rules: NIL
  Time:  0.01 seconds (prove: 0.00, print: 0.00, other: 0.01)
   MAC
  ACL2 !>(trace$ member-equal member-eq-exec)
   ((MEMBER-EQUAL) (MEMBER-EQ-EXEC))
  ACL2 !>(defun f () (mac (a b c d)))
  1> (ACL2_*1*_ACL2::MEMBER-EQ-EXEC C (A B C D))
    2> (MEMBER-EQ-EXEC C (A B C D))
    <2 (MEMBER-EQ-EXEC (C D))
  <1 (ACL2_*1*_ACL2::MEMBER-EQ-EXEC (C D))
  1> (ACL2_*1*_ACL2::MEMBER-EQUAL C (A B C D))
    2> (MEMBER-EQUAL C (A B C D))
    <2 (MEMBER-EQUAL (C D))
  <1 (ACL2_*1*_ACL2::MEMBER-EQUAL (C D))

  Since F is non-recursive, its admission is trivial.
 })

 <p>If performance is an issue then we can avoid such a problem, for example as
 follows.  In a fresh session, let us define a suitable wrapper for calling
 @(tsee member) with @(':TEST 'eq').  This time, the trace in our partial log
 shows that we have avoided calling two membership functions.</p>

 @({
  ACL2 !>(defun mem-eq (x lst)
           (declare (xargs :guard (if (symbolp x)
                                      (true-listp lst)
                                    (symbol-listp lst))))
           (member x lst :test 'eq))
  [[ ... output omitted here ... ]]
   MEM-EQ
  ACL2 !>(defmacro mac (lst)
           (list 'quote (and (true-listp lst)
                             (mem-eq 'c lst))))

  Summary
  Form:  ( DEFMACRO MAC ...)
  Rules: NIL
  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
   MAC
  ACL2 !>(trace$ member-equal member-eq-exec mem-eq)
   ((MEMBER-EQUAL)
    (MEMBER-EQ-EXEC)
    (MEM-EQ))
  ACL2 !>(defun f () (mac (a b c d)))
  1> (ACL2_*1*_ACL2::MEM-EQ C (A B C D))
    2> (MEM-EQ C (A B C D))
    <2 (MEM-EQ (C D))
  <1 (ACL2_*1*_ACL2::MEM-EQ (C D))

  Since F is non-recursive, its admission is trivial.
 })")

(defxdoc equivalence
  :parents (rule-classes)
  :short "Mark a relation as an equivalence relation"
  :long "<p>See @(see rule-classes) for a general discussion of rule classes,
 including how they are used to build rules from formulas and a discussion of
 the various keywords in a rule class description.</p>

 @({
  Example:
  (defthm r-equal-is-an-equivalence ; assumes that r-equal has been defined
    (and (booleanp (r-equal x y))
         (r-equal x x)
         (implies (r-equal x y) (r-equal y x))
         (implies (and (r-equal x y)
                       (r-equal y z))
                  (r-equal x z)))
    :rule-classes :equivalence)
 })

 <p>Also see @(see defequiv).</p>

 @({
  General Form:
  (and (booleanp (equiv x y))
       (equiv x x)
       (implies (equiv x y) (equiv y x))
       (implies (and (equiv x y)
                     (equiv y z))
                (equiv x z)))
 })

 <p>except that the order of the conjuncts and terms and the choice of variable
 symbols is unimportant.  The effect of such a rule is to identify @('equiv')
 as an equivalence relation.  Note that only Boolean 2-place function symbols
 can be treated as equivalence relations.  See @(see congruence) and see @(see
 refinement) for closely related concepts.</p>

 <p>The macro form @('(defequiv equiv)') is an abbreviation for a @(tsee
 defthm) of rule-class @(':equivalence') that establishes that @('equiv') is an
 equivalence relation.  It generates the formula shown above.  See @(see
 defequiv).</p>

 <p>When @('equiv') is marked as an equivalence relation, its reflexivity,
 symmetry, and transitivity are built into the system in a deeper way than via
 @(':')@(tsee rewrite) rules.  More importantly, after @('equiv') has been
 shown to be an equivalence relation, lemmas about @('equiv'), e.g.,</p>

 @({
  (implies hyps (equiv lhs rhs)),
 })

 <p>when stored as @(':')@(tsee rewrite) rules, cause the system to rewrite
 certain occurrences of (instances of) @('lhs') to (instances of) @('rhs').
 Roughly speaking, an occurrence of @('lhs') in the @('kth') argument of some
 @('fn')-expression, @('(fn ... lhs' ...)'), can be rewritten to produce @('(fn
 ...  rhs' ...)'), provided the system ``knows'' that the value of @('fn') is
 unaffected by @('equiv')-substitution in the @('kth') argument.  Such
 knowledge is communicated to the system via ``congruence lemmas.''</p>

 <p>For example, suppose that @('r-equal') is known to be an equivalence
 relation.  The @(':')@(tsee congruence) lemma</p>

 @({
  (implies (r-equal s1 s2)
           (equal (fn s1 n) (fn s2 n)))
 })

 <p>informs the rewriter that, while rewriting the first argument of
 @('fn')-expressions, it is permitted to use @('r-equal') rewrite-rules.  See
 @(see congruence) for details about @(':')@(tsee congruence) lemmas.
 Interestingly, congruence lemmas are automatically created when an equivalence
 relation is stored, saying that either of the equivalence relation's arguments
 may be replaced by an equivalent argument.  That is, if the equivalence
 relation is @('fn'), we store congruence rules that state the following
 fact:</p>

 @({
  (implies (and (fn x1 y1)
                (fn x2 y2))
           (iff (fn x1 x2) (fn y1 y2)))
 })

 <p>Another aspect of equivalence relations is that of ``refinement.''  We say
 @('equiv1') ``refines'' @('equiv2') iff @('(equiv1 x y)') implies @('(equiv2 x
 y)').  @(':')@(tsee refinement) rules permit you to establish such connections
 between your equivalence relations.  The value of refinements is that if the
 system is trying to rewrite something while maintaining @('equiv2') it is
 permitted to use as a @(':')@(tsee rewrite) rule any refinement of
 @('equiv2').  Thus, if @('equiv1') is a refinement of @('equiv2') and there
 are @('equiv1') rewrite-rules available, they can be brought to bear while
 maintaining @('equiv2').  See @(see refinement).</p>

 <p>The system initially has knowledge of two equivalence relations, equality,
 denoted by the symbol @(tsee equal), and propositional equivalence, denoted by
 @(tsee iff).  @(tsee Equal) is known to be a refinement of all equivalence
 relations and to preserve equality across all arguments of all functions.</p>

 <p>Typically there are five steps involved in introducing and using a new
 equivalence relation, equiv.</p>

 <blockquote>

 <p>(1) Define @('equiv'),</p>

 <p>(2) prove the @(':equivalence') lemma about @('equiv'),</p>

 <p>(3) prove the @(':')@(tsee congruence) lemmas that show where @('equiv')
 can be used to maintain known relations,</p>

 <p>(4) prove the @(':')@(tsee refinement) lemmas that relate @('equiv') to
 known relations other than equal, and</p>

 <p>(5) develop the theory of conditional @(':')@(tsee rewrite) rules that
 drive equiv rewriting.</p>

 </blockquote>

 <p>More will be written about this as we develop the techniques.  For now,
 here is an example that shows how to make use of equivalence relations in
 rewriting.</p>

 <p>Among the theorems proved below is</p>

 @({
  (defthm insert-sort-is-id
    (perm (insert-sort x) x))
 })

 <p>Here @('perm') is defined as usual with @('delete') and is proved to be an
 equivalence relation and to be a congruence relation for @(tsee cons) and
 @(tsee member).</p>

 <p>Then we prove the lemma</p>

 @({
  (defthm insert-is-cons
    (perm (insert a x) (cons a x)))
 })

 <p>which you must think of as you would @('(insert a x) = (cons a x)').</p>

 <p>Now prove @('(perm (insert-sort x) x)').  The base case is trivial.  The
 induction step is</p>

 @({
     (consp x)
   & (perm (insert-sort (cdr x)) (cdr x))

  -> (perm (insert-sort x) x).
 })

 <p>Opening @('insert-sort') makes the conclusion be</p>

 @({
     (perm (insert (car x) (insert-sort (cdr x))) x).
 })

 <p>Apply @('insert-is-cons') to get</p>

 @({
  (perm (cons (car x) (insert-sort (cdr x)) x)).
 })

 <p>Note that we have proved that @('perm') is a congruence relation for
 @('cons'). That allows us to apply the induction hypothesis (rewriting
 @('(insert-sort (cdr x))') to @('(cdr x)')), to make the conclusion be</p>

 @({
  (perm (cons (car x) (cdr x)) x).
 })

 <p>But we know that @('(cons (car x) (cdr x))') is @('x'), so we get @('(perm
 x x)') which is trivial, since @('perm') is an equivalence relation.  An
 exercise left to the reader is how this proof will change had we also proved
 that @('perm') is a congruence relation for @('insert').</p>

 <p>Here are the events.</p>

 @({
  (encapsulate (((lt * *) => *))
    (local (defun lt (x y) (declare (ignore x y)) nil))
    (defthm lt-non-symmetric (implies (lt x y) (not (lt y x)))))

  (defun insert (x lst)
    (cond ((atom lst) (list x))
          ((lt x (car lst)) (cons x lst))
          (t (cons (car lst) (insert x (cdr lst))))))

  (defun insert-sort (lst)
    (cond ((atom lst) nil)
          (t (insert (car lst) (insert-sort (cdr lst))))))

  (defun del (x lst)
    (cond ((atom lst) nil)
          ((equal x (car lst)) (cdr lst))
          (t (cons (car lst) (del x (cdr lst))))))

  (defun mem (x lst)
    (cond ((atom lst) nil)
          ((equal x (car lst)) t)
          (t (mem x (cdr lst)))))

  (defun perm (lst1 lst2)
    (cond ((atom lst1) (atom lst2))
          ((mem (car lst1) lst2)
           (perm (cdr lst1) (del (car lst1) lst2)))
          (t nil)))

  (defthm perm-reflexive
    (perm x x))

  (defthm perm-cons
    (implies (mem a x)
             (equal (perm x (cons a y))
                    (perm (del a x) y)))
    :hints (("Goal" :induct (perm x y))))

  (defthm perm-symmetric
    (implies (perm x y) (perm y x)))

  (defthm mem-del
    (implies (mem a (del b x)) (mem a x)))

  (defthm perm-mem
    (implies (and (perm x y)
                  (mem a x))
             (mem a y)))

  (defthm mem-del2
    (implies (and (mem a x)
                  (not (equal a b)))
             (mem a (del b x))))

  (defthm comm-del
    (equal (del a (del b x)) (del b (del a x))))

  (defthm perm-del
    (implies (perm x y)
             (perm (del a x) (del a y))))

  (defthm perm-transitive
    (implies (and (perm x y) (perm y z)) (perm x z)))

  (defequiv perm)

  (in-theory (disable perm
                      perm-reflexive
                      perm-symmetric
                      perm-transitive))

  (defcong perm perm (cons x y) 2)

  (defcong perm iff (mem x y) 2)

  (defthm atom-perm
    (implies (not (consp x)) (perm x nil))
    :rule-classes :forward-chaining
    :hints (("Goal" :in-theory (enable perm))))

  (defthm insert-is-cons
    (perm (insert a x) (cons a x)))

  (defthm insert-sort-is-id
    (perm (insert-sort x) x))

  (defun app (x y) (if (consp x) (cons (car x) (app (cdr x) y)) y))

  (defun rev (x)
    (if (consp x) (app (rev (cdr x)) (list (car x))) nil))

  (defcong perm perm (app x y) 2)

  (defthm app-cons
    (perm (app a (cons b c)) (cons b (app a c))))

  (defthm app-commutes
    (perm (app a b) (app b a)))

  (defcong perm perm (app x y) 1
    :hints (("Goal" :induct (app y x))))

  (defthm rev-is-id (perm (rev x) x))

  (defun == (x y)
    (if (consp x)
        (if (consp y)
            (and (equal (car x) (car y))
                 (== (cdr x) (cdr y)))
            nil)
        (not (consp y))))

  (defthm ==-reflexive (== x x))

  (defthm ==-symmetric (implies (== x y) (== y x)))

  (defequiv ==)

  (in-theory (disable ==-symmetric ==-reflexive))

  (defcong == == (cons x y) 2)

  (defcong == iff (consp x) 1)

  (defcong == == (app x y) 2)

  (defcong == == (app x y) 1)

  (defthm rev-rev (== (rev (rev x)) x))
 })")

(defxdoc equivalent-formulas-different-rewrite-rules
  :parents (introduction-to-the-theorem-prover)
  :short "Logically equivalent formulas can generate radically different rules"
  :long "<p>Consider the rewrite rules that would be generated from the three
 commands below.  In all three cases, the fact being stated relates the
 @('n')th element of the reverse of @('x') to the @('n')th element of @('x').
 In fact, the three formulas are simple rearrangements of each other and are
 all equivalent.  The theorem prover treats all three formulas equivalently
 when proving them.  But the rules generated from them are very different.</p>

 @({
  (defthm nth-rev-1
    (implies (and (natp n)
                  (< n (len x)))
             (equal (nth n (rev x))
                    (nth (- (len x) (+ 1 n)) x))))

  (defthm nth-rev-2
    (implies (and (natp n)
                  (< n (len x)))
             (equal (nth (- (len x) (+ 1 n)) x)
                    (nth n (rev x)))))

  (defthm nth-rev-3
    (implies (and (natp n)
                  (not (equal (nth n (rev x))
                              (nth (- (len x) (+ 1 n)) x))))
             (not (< n (len x)))))
 })

 <p>Here are the three rewrite rules:</p>

 <p><b>nth-rev-1</b>:<br></br>

 Replace instances of @('(NTH n (REV x))')<br></br>

 by @('(NTH (- (LEN x) (+ 1 n)) x)'),<br></br>

 if you can establish that @('n') is a natural number less than the length of
 @('x').</p>

 <p><b>nth-rev-2</b>:<br></br>

 Replace instances of @('(NTH (- (LEN x) (+ 1 n)) x)')<br></br>

 by @('(NTH n (REV x))'),<br></br>

 if you can establish that @('n') is a natural number less than the length of
 @('x').</p>

 <p><b>nth-rev-3</b>:<br></br>

 Replace instances of @('(< n (LEN x))')<br></br>

 by @('NIL')<br></br>

 if you can establish that @('n') is a natural number and that @('(NTH n (REV
 x))') is different from @('(NTH (- (LEN x) (+ 1 n)) x)').</p>

 <p>As the driver of ACL2, you have to decide which rule you want <i>when you
 give the command to prove it</i>.</p>

 <p>If you tell the theorem prover to use both @('nth-rev-1') and
 @('nth-rev-2'), ACL2 will enter an infinite loop when it sees any term
 matching either @('NTH') expression.</p>

 <p>Most users would choose form @('nth-rev-1') of the rule.  It eliminates
 @('rev') from the problem &mdash; at the expense of introducing some
 arithmetic.  But arithmetic is so fundamental it is rarely possible to avoid
 it and it is likely to be in the problem already since you're indexing into
 @('(rev x)').  The @('nth-rev-2') form of the rule is ``bad'' because it
 introduces @('rev') into a problem where it might not have appeared.  The
 @('nth-rev-3') version is ``bad'' because it makes the theorem prover shift
 its attention from a simple arithmetic inequality to a complicated property of
 @('nth') and @('rev'), which might not be in the problem.</p>

 <p>Use your browser's <b>Back Button</b> now to return to @(see
 introduction-to-rewrite-rules-part-1).</p>")

(defxdoc er
  :parents (errors acl2-built-ins)
  :short "Print an error message and ``cause an error''"
  :long "<p>See @(see fmt) for a general discussion of formatted printing in
 ACL2.  All calls of @('er') print formatted strings, just as is done by @(tsee
 fmt).</p>

 @({
  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 hard! 'top-level "Illegal inputs, ~x0 and ~x1." a b)
  (er soft  'top-level "Illegal inputs, ~x0 and ~x1." a b)
  (er-soft  'top-level "Illegal-inputs" "Illegal inputs, ~x0 and ~x1." a b)
 })

 <p>The examples above all print an error message to standard output saying
 that (the values of) @('a') and @('b') are illegal inputs.  However, the first
 three &mdash; which we call <i>hard errors</i> &mdash; abort evaluation after
 printing an error message (while logically returning @('nil'), though in
 ordinary evaluation the return value is never seen); while the last two
 &mdash; so-called <i>soft errors</i> &mdash; return an @(see error-triple),
 @('(mv t nil state)'), after printing an error message.  The result in each of
 the two soft error cases can be interpreted as an ``error'' when programming
 with the ACL2 @(tsee state), something most ACL2 users will probably not want
 to do unless they are building systems of some sort; see @(see
 programming-with-state).  If state is not available in the current context
 then you will probably want to cause a hard error; for example, if you are
 returning two values, you may write @('(mv (er hard ...) nil)').</p>

 <p>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').</p>

 <p>The difference between the @('hard') and @('hard!') forms is that there are
 situations in which @('(er hard ...)') returns @('nil') rather than causing an
 error, while @('(er hard! ...)') will always cause an error (though such
 errors are sometimes ``caught'', for example during proofs).  You will
 probably be happy using @('hard') rather than considering the use of
 @('hard!'), which is really provided mostly for system implementors; but you
 can try @('hard!') if you are not getting the errors you expect.  There is
 even an additional option, @('hard?!'), which avoids guard proof obligations
 like @('hard?') but ensures errors like @('hard!').</p>

 <p>@('Er') is a macro, and the examples above expand to calls of ACL2
 functions; see below.  Also see @(see illegal), @(see hard-error), and @(see
 error1).  The @('hard?')/@('hard?!') forms have expansions that call the
 function @(tsee hard-error), which has a @(see guard) of @('T'), while the
 @('hard')/@('hard!') forms have expansions that call the function @(tsee
 illegal), which has a guard that is logically @('NIL').  Those generate code
 that is in @(':')@(tsee logic) mode, as do variants of @('(er soft ...)').
 The soft error forms expand to calls of the function @(tsee error1), which
 necessarily takes @(tsee state) as an explicit argument since it returns an
 @(see error-triple).  The guard for the soft error forms is that of @(tsee
 error1).  Note in particular that soft errors require the state to satisfy
 certain restrictions beyond just the usual @('state-p') predicate.</p>

 <p>The general forms of the macros are as follows.  Their macroexpansions
 include code that avoids the printing of error messages when error output is
 inhibited &mdash; see @(see set-inhibit-output-lst) &mdash; but here we show
 only the essential function calls.  Note that all arguments are evaluated even
 when error output is inhibited.</p>

 @({
  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 hard! ctx fmt-string arg1 arg2 ... argk)
    ; logically is same as (er hard ...), but always produces an error

  (er soft  ctx fmt-string arg1 arg2 ... argk)
    ==> {macroexpands, in essence, to:}
  (ERROR1     CTX NIL FMT-STRING
              (LIST (CONS #\0 ARG1) (CONS #\1 ARG2) ... (CONS #\k ARGk)))

  (er-soft  ctx summary fmt-string arg1 arg2 ... argk)
    ==> {macroexpands, in essence, to:}
  (ERROR1     CTX SUMMARY FMT-STRING
              (LIST (CONS #\0 ARG1) (CONS #\1 ARG2) ... (CONS #\k ARGk)))
 })

 <p>See @(see ctx) for the possible forms of the @('ctx') argument.</p>

 <p>Technical note for raw Lisp programmers only: It is possible to cause hard
 errors to signal actual raw Lisp errors.  See @(see hard-error).</p>")

(defxdoc er-hard
  :parents (errors acl2-built-ins)
  :short "Print an error message and ``cause a hard error''"
  :long "<p>See @(see er) for relevant background, which is assumed below, and
 related utilities.</p>

 @({
 General Form:
 (er-hard context summary str &rest str-args)
 })

 <p>where context is a legal context (see @(see ctx)), @('summary') is @('nil')
 or a string, @('str') is a string, and @('str-args') are @('tsee fmt')
 arguments for @('str').  Note that @('(er-hard context summary str ...)') is
 equivalent to @('(er hard context (cons summary str) ...)').  The use of a
 non-@('nil') @('summary') allows suppression of this error message without
 suppressing all error output; see @(see set-inhibit-er).</p>

 <p>Calls of @('er-hard') expand much like calls @('(er hard ...)'), in the
 sense that both expand to calls of the function, @(tsee illegal), which has a
 @(see guard) equivalent to @('nil').  See @(see er-hard?) for a similar
 utility that avoids generating guard obligations.</p>

 <p>See @(tsee er-soft) for a similar utility pertaining to ``soft''
 errors.</p>")

(defxdoc er-hard?
  :parents (errors acl2-built-ins)
  :short "Print an error message and ``cause a hard error''"
  :long "<p>See @(see er-hard) for a nearly identical utility that is aligned
  with @('(er hard ...)'), generating a @(see guard) obligation of @('nil').
  By contrast, @('(er-hard? ...)') is aligned with @('(er hard? ...)')): these
  do not generate guard obligations.  This distinction is due to the fact that
  a call of @('(er-hard ...)') macroexpands to a call of the function, @(tsee
  illegal), while a call of @('(er-hard? ...)') macroexpands to a call of the
  function, @(tsee hard-error).</p>

 @({
 General Form:
 (er-hard? context summary str &rest str-args)
 })

 <p>Other than the difference in guard obligations generated, as discussed
 above, @('er-hard?') behaves identically to @('er-hard').  See @(see er-hard)
 and for relevant background, see @(see er).</p>")

(defxdoc er-progn
  :parents (errors programming-with-state acl2-built-ins)
  :short "Perform a sequence of state-changing ``error triples''"
  :long "@({
  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))))
 })

 <p>This sequencing primitive is only useful when programming with @(see
 state), something that very few users will probably want to do.  See @(see
 state).</p>

 <p>@('Er-progn') is used much the way that @(tsee progn) is used in Common
 Lisp, except that it expects each form within it to evaluate to an @(see
 error-triple) of the form @('(mv erp val state)').  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 @('er-progn') form returns the value of the last form.</p>

 @({
  General Form:
  (er-progn <expr1> ... <exprk>)
 })

 <p>where each @('<expri>') is an expression that evaluates to an error triple
 (see @(see programming-with-state)).  The above form is essentially equivalent
 to the following (``essentially'' because in fact, care is taken to avoid
 variable capture).</p>

 @({
  (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>)))))))))
 })")

(defxdoc er-soft
  :parents (errors acl2-built-ins)
  :short "Print an error message and ``cause a soft error''"
  :long "<p>See @(see er) for relevant background, which is assumed below, and
 related utilities.</p>

 @({
 General Form:
 (er-soft context summary str &rest str-args)
 })

 <p>where context is a legal context (see @(see ctx)), @('summary') is @('nil')
 or a string, @('str') is a string, and @('str-args') are @('tsee fmt')
 arguments for @('str').  The use of a non-@('nil') @('summary') allows
 suppression of this error message without suppressing all error output; see
 @(see set-inhibit-er).</p>

 <p>See @(tsee er-hard) for a similar utility pertaining to ``hard''
 errors.</p>")

(defxdoc error-triple
  :parents (errors programming-with-state)
  :short "A common ACL2 programming idiom"
  :long "<p>When evaluation returns three values, where the first two are
 ordinary (non-@(see stobj)) objects and the third is the ACL2 @(see state),
 the result may be called an ``error triple'' or ``error-triple''.  If an error
 triple is @('(mv erp val state)'), we think of @('erp') as an error flag and
 @('val') as the returned value.  By default, if the result of evaluating a
 top-level form is an error triple @('(mv erp val state)'), then that result is
 not printed if @('erp') is non-@('nil') or if @('val') is the keyword
 @(':INVISIBLE'), and otherwise @('val') is printed with a preceding space.
 For example:</p>

 @({
  ACL2 !>(+ 3 4) ; ordinary value
  7
  ACL2 !>(mv nil (+ 3 4) state) ; error triple, error component of nil
   7
  ACL2 !>(mv t (+ 3 4) state) ; error triple, non-nil error component
  ACL2 !>(mv nil :invisible state) ; special case for :INVISIBLE
  ACL2 !>
 })

 <p>In certain settings, notably when printing evaluation results, multiple
 values @('(mv erp val state)') may be considered an error triple even when
 @('val') is a @(see df) rather than an ordinary object.  Here is an example;
 see @(see df) for more about how floating-point numbers are simulated in
 ACL2.</p>

 @({
 ACL2 !>(mv nil (to-df 3) state)
  #d3.0
 ACL2 !>
 })

 <p>See @(see programming-with-state) for a discussion of error triples and how
 to program with them.  Also see @(see ld-error-triples) and see @(see ld) for
 a discussion of the value @(':COMMAND-CONVENTIONS') for keyword
 @(':LD-POST-EVAL-PRINT').</p>")

(defxdoc error-triples-and-parallelism
  :parents (parallel-programming)
  :short "How to avoid error triples in ACL2(p)"
  :long "<p>This @(see documentation) topic relates to the experimental
 extension of ACL2 supporting parallel execution and proof; see @(see
 parallelism).</p>

 <p>ACL2 supports the use of error triples in many features; e.g., @(tsee
 computed-hints).  (For background on error triples, see @(see
 programming-with-state).)  However, ACL2(p) does not support the use of error
 triples in some of these features (e.g., @(tsee computed-hints)) while @(see
 waterfall-parallelism) is enabled.</p>

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

 @({
  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.
 })

 <p>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 @(see unsupported-waterfall-parallelism-features)
 for other related information).</p>

 <p>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 @(tsee cw) or @(tsee observation-cw).
 If the user is concerned about the interleaving of their output with other
 output, these calls can be surrounded with the macro @(tsee
 with-output-lock).</p>

 <p>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
 @(tsee er) with the @('hard') or @('hard?') severity.  By using these
 mechanisms, the user avoids modifying @(tsee state), a requirement for much of
 the code written in ACL2(p).</p>

 <p>You may encounter other similar error messages when using @(see
 computed-hints), @(see custom-keyword-hints), or @(see 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.</p>")

(defxdoc error1
  :parents (errors acl2-built-ins)
  :short "Print an error message and cause a ``soft error''"
  :long "<p>@('(Error1 ctx summary str alist state)') returns @('(mv t nil
 state)').  An error message is first printed using the ``context'' @('ctx'),
 as well as the string @('str') and alist @('alist') that are of the same kind
 as expected by @(tsee fmt) &mdash; unless error output is inhibited
 (see @(see set-inhibit-output-lst) and @(see with-output)) or @('summary') is
 non-@('nil'), in which case it is a string, and error output of that type is
 inhibited (see @(see set-inhibit-er)).  See @(see fmt).</p>

 <p>@('Error1') can be interpreted as causing an ``error'' when programming
 with the ACL2 @(tsee state), something most ACL2 users will probably not want
 to do; see @(see ld-error-triples) and see @(see er-progn).  However, @('error1')
 is a guard verified @(tsee logic) mode function whose guard is</p>

 @({
 (AND (STATE-P STATE)
      (STRINGP STR)
      (ERROR1-STATE-P STATE)
      (CHARACTER-ALISTP ALIST)
      (OR (NULL SUMMARY) (STRINGP SUMMARY)))
 })

 <p>Note in particular that the state must not only satisfy the basic
 recognizer, @('state-p'), for ACL2 states but must also satisfy
 @('error1-state-p'), which includes additional restrictions ensuring that
 @('error1') can print formatted output to the standard character output
 channel, @(tsee standard-co), interpret the table maintained by @(tsee
 set-inhibit-er), etc.  If the complexity of @(see error1)'s guard discourages
 you from using it in guard-verified logic mode systems you may wish to cause a
 @(see hard-error) with @(tsee illegal) or the more unified way of signaling
 errors with the macro @(tsee er).</p>

 <p>As mentioned above, @('error1') always returns @('(mv t nil state)').  But
 if a call @('(error1 ctx summary str alist)') is encountered during
 evaluation, then unless output is inhibited as described above, the string
 @('str') is first printed using the association list @('alist') (as in @(tsee
 fmt)).  Here is a trivial, contrived example.</p>

 @({
  ACL2 !>(error1 'my-context
                 "Printing 4: ~n0"
                 (list (cons #\0 4))
                 state)

  ACL2 Error in MY-CONTEXT:  Printing 4: four

  ACL2 !>
 })")

(defxdoc errors
  :parents (programming)
  :short "Support for causing runtime errors, breaks, assertions, etc.")

(defxdoc escape-to-common-lisp
  :parents (common-lisp)
  :short "Escaping to Common Lisp"
  :long "@({
  Example:
  ACL2 !>:Q
 })

 <p>There is essentially no Common Lisp escape feature in the ACL2 loop (see
 @(see lp)).  (A potentially unsound exception is raw-mode; see @(see
 set-raw-mode).)  This is part of the price of purity.  To execute a form in
 Common Lisp as opposed to ACL2, exit @(tsee lp) with @(':q'), submit the
 desired forms to the Common Lisp read-eval-print loop, and reenter ACL2 with
 @('(lp)').  WARNING: Doing so is potentially unsound; see @(see q).</p>")

(defxdoc ev$
  :parents (apply$)
  :short "Evaluate a tame expression using @('apply$')"
  :long "<p>When @(tsee apply$), actually @(tsee apply$-lambda), is asked to
  apply a @('LAMBDA') object to some arguments it calls @('ev$') on the body of
  the object and an alist binding the formals of the object to the arguments.
  Roughly put, @('ev$') ``works'' by looking up symbols, returning quoted
  objects, and using @('apply$') to apply function symbols to the results of
  evaluating their arguments.  @('Ev$') and its clique-mate @('ev$-list') are
  mutually-recursive with @('apply$').  @('Ev$') can only evaluate ``as
  expected'' on @(see tame) expressions and requires @(tsee warrant)s, explicit
  in the proof theory or implicit in the evaluation theory, to determine @(see
  badge)s and thus tameness.  See @(tsee apply$) for details, including the
  formal definitions of @('ev$') and @('ev$-list').  For a summary of how the
  rewriter handles @('apply$'), @('ev$'), and @('loop$') @(see scion)s, see
  @(see rewriting-calls-of-apply$-ev$-and-loop$-scions).</p>")

(defxdoc evaluation
  :parents (programming)
  :short "Evaluating ACL2 expressions"
  :long "<p>This topic uses examples to expose how ACL2 uses Common Lisp to
 evaluate expressions.  Links are provided to topics that elaborate on
 aspects of evaluation in ACL2.</p>

 <p>At a high level, we can say that ACL2 evaluation takes place using the
 underlying host Common Lisp.  But consider the form @('(car 3)').  In Common
 Lisp this is an error; typically you will be thrown into the Lisp debugger.
 In the ACL2 read-eval-print loop, however, you may see the following.</p>

 @({
 ACL2 !>(car 3)


 ACL2 Error in TOP-LEVEL:  The guard for the function call (CAR X),
 which is (OR (CONSP X) (EQUAL X NIL)), is violated by the arguments
 in the call (CAR 3).
 See :DOC set-guard-checking for information about suppressing this
 check with (set-guard-checking :none), as recommended for new users.
 To debug see :DOC print-gv, see :DOC trace, and see :DOC wet.

 ACL2 !>
 })

 <p>The message suggests that the function @('car') has a @(see guard), or
 precondition, that is violated by the proposed argument, @('3').  So clearly
 something more is going on here than just evaluation of the form @('(car 3)')
 in Common Lisp.</p>

 <p>In fact, every ACL2 function symbol is associated with the following two
 Common Lisp definitions, as explained below:</p>

 <ul>

 <li>the ``executable-counterpart'' definition, sometimes called the ``*1*''
 function (pronounced ``star one star''); and</li>

 <li>the ``submitted'' definition (sometimes called the ``raw Lisp''
 function).</li>

 </ul>

 <p>We may also speak of the ``executable-counterpart'' and ``submitted''
 functions, which are the two functions defined by the
 ``executable-counterpart'' and ``submitted'' definitions, respectively.</p>

 <p>Let us explore these two functions in the case of @('car').  When @('(car
 3)') is evaluated in the ACL2 loop, the executable-counterpart of @('car') is
 applied to the argument @('3').  That executable-counterpart (which was
 hand-coded) first checks the guard of @('car'), which fails for @('3'),
 leading to the error displayed above.  If instead the form to be evaluated by
 ACL2 is @('(car '(4 5 6))'), the executable-counterpart of @('car') will first
 check that the guard of @('car') holds for the list argument @('(4 5 6)');
 then seeing that this is the case, it will apply the Common Lisp function
 @('car') &mdash; which we consider to be the ``submitted'' function for
 @('car') &mdash; to that list argument, returning @('4').</p>

 <p>The example above does not really explain why the submitted function is
 called ``submitted'', so let us consider the more common case of a defined
 function, as opposed to a @(see primitive) like @('car').  Suppose we define
 the following functions @('f') and @('g'), each of which has an implicit @(see
 guard) (precondition) of @('t'), i.e., the precondition always holds.</p>

 @({
 (defun f (x)
   (car x))
 (defun g (x)
   (f x))
 })

 <p>ACL2 defines two functions named @('"F"'): the executable-counterpart of
 @('f'), sometimes called ``@('*1*f')'', and the submitted function for @('f').
 It also defines two such functions for @('g').  The executable-counterpart is
 generated by ACL2 to include not only code to check guards, but also code to
 invoke the executable-counterparts of its callees.  (Such invocation can be
 avoided by a process known as verifying guards, as we explain further below.)
 We can see what is going on by tracing calls of @('f') (see @(see trace) for
 more about tracing); some analysis follows below this display.</p>

 @({
 ACL2 !>(trace$ f g)
  ((F) (G))
 ACL2 !>(g '(4 5 6))
 1> (ACL2_*1*_ACL2::G (4 5 6))
   2> (ACL2_*1*_ACL2::F (4 5 6))
   <2 (ACL2_*1*_ACL2::F 4)
 <1 (ACL2_*1*_ACL2::G 4)
 4
 ACL2 !>
 })

 <p>It is now perhaps evident why sometimes we call the executable-counterpart
 functions the ``*1* functions'': the executable-counterpart is actually
 defined in a special ``*1*'' package that corresponds to the package of the
 submitted function.  The trace above shows that the executable-counterpart of
 @('g') calls the executable-counterpart of @('f'), rather than calling any
 submitted function.</p>

 <p>Such a trace can show us an error caused by applying @('car') to
 @('3').</p>

 @({
 ACL2 !>(g 3)
 1> (ACL2_*1*_ACL2::G 3)
   2> (ACL2_*1*_ACL2::F 3)


 ACL2 Error in TOP-LEVEL:  The guard for the function call (CAR X),
 which is (OR (CONSP X) (EQUAL X NIL)), is violated by the arguments
 in the call (CAR 3).
 See :DOC set-guard-checking for information about suppressing this
 check with (set-guard-checking :none), as recommended for new users.
 To debug see :DOC print-gv, see :DOC trace, and see :DOC wet.

 ACL2 !>
 })

 <p>It is generally more efficient to invoke a submitted functions &mdash;
 which has as its Common Lisp definition exactly the @(tsee defun) form
 submitted to ACL2 &mdash; than it is to invoke an executable-counterpart,
 which is generated by ACL2 to do auxiliary calculations including
 guard-checking.  So we next modify the example above to show that by
 performing a process called ``guard verification'', we can avoid *1* function
 calls, so that submitted functions are invoked instead.  This time we supply
 reasonable guards for @('f') and @('g'), in a fresh ACL2 session.</p>

 @({
 (defun f (x)
   (declare (xargs :guard (or (consp x) (null x))))
   (car x))
 (defun g (x)
   (declare (xargs :guard (consp x)))
   (f x))
 })

 <p>This time, we see that the executable-counterpart of @('g') directly calls
 the submitted function for @('g'), because @('g') was guard-verified when
 @('g') was admitted and the value @(''(4 5 6)') for the formal @('x') of
 @('g') satisfies the guard @('(consp x)') of @('g').</p>

 @({
 ACL2 !>(trace$ f g)
  ((F) (G))
 ACL2 !>(g '(4 5 6))
 1> (ACL2_*1*_ACL2::G (4 5 6))
   2> (G (4 5 6))
     3> (F (4 5 6))
     <3 (F 4)
   <2 (G 4)
 <1 (ACL2_*1*_ACL2::G 4)
 4
 ACL2 !>
 })

 <p>We can also see that because @('3') fails to satisfy the guard of @('g'), a
 guard violation is signaled by the executable-counterpart of @('g'), rather
 than (as before) by the executable-counterpart of @('car').</p>

 @({
 ACL2 !>(g 3)
 1> (ACL2_*1*_ACL2::G 3)


 ACL2 Error in TOP-LEVEL:  The guard for the function call (G X), which
 is (CONSP X), is violated by the arguments in the call (G 3).
 See :DOC set-guard-checking for information about suppressing this
 check with (set-guard-checking :none), as recommended for new users.
 To debug see :DOC print-gv, see :DOC trace, and see :DOC wet.

 ACL2 !>
 })

 <p>See if you can predict the corresponding traces if instead, @('f') has a
 suitable guard and is guard-verified, but @('g') is as in the first
 example (with an implicit guard of @('t'), and not guard-verified):</p>

 @({
 (defun f (x)
   (declare (xargs :guard (or (consp x) (null x))))
   (car x))
 (defun g (x)
   (f x))
 })

 <p>The corresponding trace is as follows; discussion follows.</p>

 @({
 ACL2 !>(g '(4 5 6))
 1> (ACL2_*1*_ACL2::G (4 5 6))
   2> (ACL2_*1*_ACL2::F (4 5 6))
     3> (F (4 5 6))
     <3 (F 4)
   <2 (ACL2_*1*_ACL2::F 4)
 <1 (ACL2_*1*_ACL2::G 4)
 4
 ACL2 !>(g 3)
 1> (ACL2_*1*_ACL2::G 3)
   2> (ACL2_*1*_ACL2::F 3)


 ACL2 Error in TOP-LEVEL:  The guard for the function call (F X), which
 is (OR (CONSP X) (NULL X)), is violated by the arguments in the call
 (F 3).
 See :DOC set-guard-checking for information about suppressing this
 check with (set-guard-checking :none), as recommended for new users.
 To debug see :DOC print-gv, see :DOC trace, and see :DOC wet.

 ACL2 !>
 })

 <p>The traces above show that first, the executable-counterpart of @('g')
 calls the executable-counterpart of @('f').  This is because @('g') is not
 guard-verified, so its executable-counterpart can only invoke other
 executable-counterparts.  However, since @('f') is guard-verified, its
 executable-counterpart invokes its submitted function when the guard is
 satisfied, for example to generate the call @('(F (4 5 6))').  If the guard
 for @('f') fails to hold, however, the executable-counterpart for @('f')
 causes a guard violation error, as shown above for the executable-counterpart
 call @('(ACL2_*1*_ACL2::F 3)').</p>

 <p>See also @(see guard) and its subtopics, especially, @(see
 guards-and-evaluation), for a discussion of guards and their connection to
 evaluation.  Advanced system hackers who want to see the
 executable-counterpart definition for @('f') may invoke @('(trace!
 (oneify-cltl-code :native t))') before defining @('f') in ACL2.</p>")

(defxdoc evaluator-restrictions
  :parents (meta)
  :short "Some restrictions on the use of evaluators in meta-level rules"
  :long "<p>Note: This topic, which explains some subtleties for evaluators,
 can probably be skipped by most readers.</p>

 <p>Rules of class @(':')@(tsee meta) and of class @(':')@(tsee
 clause-processor) are stated using so-called ``evaluator'' functions.  Here we
 explain some restrictions related to evaluators.  Below we refer primarily to
 @(':meta') rules, but the discussion applies equally to @(':clause-processor')
 rules.</p>

 <p>In a nutshell, we require that a rule's evaluator does not support any
 @(see meta-extract) functions in the rule or any @(tsee defaxiom) events, and
 we require that the evaluator not be introduced under a non-trivial
 encapsulate.  We also require that no function has an attachment (see @(see
 defattach)) that is both ancestral in the evaluator and also ancestral in the
 meta or clause-processor functions.  We explain these restrictions in detail
 below, including the notion of one function symbol being &ldquo;ancestral
 in&rdquo;, also expressed as &ldquo;an ancestor of&rdquo;, in another function
 symbol.</p>

 <p>An argument given elsewhere (see @(see meta), in particular ``Aside for the
 logic-minded'') explains that the correctness argument for applying
 metatheoretic simplifiers requires that one be able to ``grow'' an evaluator
 (see @(see defevaluator)) to handle all functions in the current ACL2 @(see
 world).  Then we may, in essence, functionally instantiate the original
 evaluator to the new (``grown'') evaluator, provided that the new evaluator
 satisfies all of the axioms of the original.  We therefore require that the
 evaluator function does not support the formula of any @(tsee defaxiom) event.
 This notion of ``support'' (sometimes denoted ``is an ancestor of'') is
 defined recursively as follows: a function symbol supports a formula if either
 it occurs in that formula, or else it supports the definition or constraint
 for some function symbol that occurs in that formula.  Moreover, we require
 that neither the evaluator function nor its list version support @(see
 meta-extract) functions if they are used in the proposed @(':meta')
 theorem.</p>

 <p>These requirements are necessary in order to carry out the functional
 instantiation argument alluded to above, as follows (where the reader may find
 it useful to have some familiarity with the paper ``Structured Theory
 Development for a Mechanized Logic'' (Journal of Automated Reasoning 26, no. 2
 (2001), pages 161-203).  By the usual conservativity argument, we know that
 the rule follows logically from the axiomatic events for its supporters.  This
 remains true if we functionally instantiate the evaluator with one
 corresponding to all the functions symbols of the current session, since none
 of the definitions of supporters of defaxioms or metafunctions are hit by that
 functional substitution.</p>

 <p>Notice though that the argument above depends on knowing that the rule is
 not itself an axiom about the evaluator!  Therefore, we also restrict
 evaluators so that they are not defined in the scope of a superior @(tsee
 encapsulate) event with non-empty signature, in order to avoid an even more
 subtle problem.  The aforementioned correctness argument depends on knowing
 that the rule is provable from the axioms on the evaluator and metafunction
 (and hypothesis metafunction, if any).  The additional restriction avoids
 unsoundness!  The following events, if allowed, produce a proof that @('(f
 x)') equals @('t') even though, as shown below, that does not follow logically
 from the axioms introduced.</p>

 @({
  ; Introduce our metafunction.
  (defun my-cancel (term)
    (case-match term
      (('f ('g))
       *t*)
      (& term)))

  ; Introduce our evaluator and prove our meta rule, but in the same
  ; encapsulate!
  (encapsulate
   ((f (x) t))

   (local (defun f (x) (declare (ignore x)) t))

   (defevaluator evl evl-list
     ((f x)))

   (defthm correctness-of-my-cancel
     (equal (evl x a)
            (evl (my-cancel x) a))
     :rule-classes ((:meta :trigger-fns (f)))))

  ; Prove that (f x) = t.
  (encapsulate
   ()

   (local (defstub c () t))

   (local (encapsulate
           ()
           (local (defun g () (c)))
           (local (in-theory (disable g (g))))
           (local (defthm f-g
                    (equal (f (g)) t)
                    :rule-classes nil))
           (defthm f-c
             (equal (f (c)) t)
             :hints (("Goal" :use f-g
                      :in-theory (e/d (g) (correctness-of-my-cancel))))
             :rule-classes nil)))

   (defthm f-t
     (equal (f x) t)
     :hints (("Goal" :by (:functional-instance
                          f-c
                          (c (lambda () x)))))
     :rule-classes nil))
 })

 <p>To see that the term @('(equal (f x) t)') does not follow logically from
 the axiomatic @(see events) above, consider following the above definition of
 @('my-cancel') with the following @(see events) instead.</p>

 @({
  ; (defun my-cancel (term) ...) as before, then:

  (defun f (x)
    (not x))

  (defun g ()
    nil)

  (defevaluator evl evl-list
     ((f x) (g)))
 })

 <p>These events imply the axiomatic events above, because we still have the
 definition of @('my-cancel'), we have a stronger @(tsee defevaluator) event,
 and we can now prove @('correctness-of-my-cancel') exactly as it is stated
 above.  So, the rule @('f-t') is a logical consequence of the chronology of
 the current session.  However, in the current session we can also prove the
 following rule, which contradicts @('f-t').</p>

 @({
  (defthm f-not-t
    (equal (f t) nil)
    :rule-classes nil)
 })

 <p>It follows that the current session logically yields a contradiction!</p>

 <p>Erik Reeber has taken the above example and modified it to prove @('nil')
 in ACL2 Version_3.1, as follows.</p>

 @({
  (in-package "ACL2")

  (defun my-cancel (term)
     (case-match term
       (('f ('g))
        *t*)
       (('f2 ('g2))
        *t*)
       (& term)))

  (defun f2 (x)
     (not x))

  (defun g2 ()
     nil)

  (encapsulate
    ((f (x) t))

    (local (defun f (x) (declare (ignore x)) t))

    (defevaluator evl evl-list
      ((f x)
       (f2 x)
       (g2)))

    (defthm correctness-of-my-cancel
      (equal (evl x a)
             (evl (my-cancel x) a))
      :rule-classes ((:meta :trigger-fns (f)))))

  (encapsulate
    ()

    (local (defstub c () t))

    (local (encapsulate
            ()
            (local (defun g () (c)))
            (local (in-theory (disable g (g))))
            (local (defthm f-g
                     (equal (f (g)) t)
                     :rule-classes nil))
            (defthm f-c
              (equal (f (c)) t)
              :hints (("Goal" :use f-g
                       :in-theory (e/d (g) (correctness-of-my-cancel))))
              :rule-classes nil)))

    (defthm f-t
      (equal (f x) t)
      :hints (("Goal" :by (:functional-instance
                           f-c
                           (c (lambda () x)))))
      :rule-classes nil))

  (defun g ()
     nil)

  ; Below is the expansion of the following defevaluator, changed slightly as
  ; indicated by comments.
  ; (defevaluator evl2 evl2-list ((f x) (f2 x) (g) (g2)))

  (ENCAPSULATE
    (((EVL2 * *) => *)
     ((EVL2-LIST * *) => *))
    (SET-INHIBIT-WARNINGS "theory")
    (LOCAL (IN-THEORY *DEFEVALUATOR-FORM-BASE-THEORY*))
    (LOCAL
     (MUTUAL-RECURSION (DEFUN EVL2 (X A)
                         (DECLARE (XARGS :VERIFY-GUARDS NIL
                                         :MEASURE (ACL2-COUNT X)
                                         :WELL-FOUNDED-RELATION O<
                                         :MODE :LOGIC))
                         (COND ((SYMBOLP X) (CDR (ASSOC-EQ X A)))
                               ((ATOM X) NIL)
                               ((EQ (CAR X) 'QUOTE) (CAR (CDR X)))
                               ((CONSP (CAR X))
                                (EVL2 (CAR (CDR (CDR (CAR X))))
                                      (PAIRLIS$ (CAR (CDR (CAR X)))
                                                (EVL2-LIST (CDR X) A))))
                               ((EQUAL (CAR X) 'F) ; changed f to f2 just below
                                (F2 (EVL2 (CAR (CDR X)) A)))
                               ((EQUAL (CAR X) 'F2)
                                (F2 (EVL2 (CAR (CDR X)) A)))
                               ((EQUAL (CAR X) 'G) (G))
                               ((EQUAL (CAR X) 'G2) (G2))
                               (T NIL)))
                       (DEFUN EVL2-LIST (X-LST A)
                         (DECLARE (XARGS :MEASURE (ACL2-COUNT X-LST)
                                         :WELL-FOUNDED-RELATION O<))
                         (COND ((ENDP X-LST) NIL)
                               (T (CONS (EVL2 (CAR X-LST) A)
                                        (EVL2-LIST (CDR X-LST) A)))))))

    (DEFTHM EVL2-CONSTRAINT-1
      (IMPLIES (SYMBOLP X)
               (EQUAL (EVL2 X A)
                      (CDR (ASSOC-EQ X A)))))
    (DEFTHM EVL2-CONSTRAINT-2
      (IMPLIES (AND (CONSP X) (EQUAL (CAR X) 'QUOTE))
               (EQUAL (EVL2 X A) (CADR X))))
    (DEFTHM EVL2-CONSTRAINT-3
      (IMPLIES (AND (CONSP X) (CONSP (CAR X)))
               (EQUAL (EVL2 X A)
                      (EVL2 (CADDAR X)
                            (PAIRLIS$ (CADAR X)
                                      (EVL2-LIST (CDR X) A))))))
    (DEFTHM EVL2-CONSTRAINT-4
      (IMPLIES (NOT (CONSP X-LST))
               (EQUAL (EVL2-LIST X-LST A) NIL)))
    (DEFTHM EVL2-CONSTRAINT-5
      (IMPLIES (CONSP X-LST)
               (EQUAL (EVL2-LIST X-LST A)
                      (CONS (EVL2 (CAR X-LST) A)
                            (EVL2-LIST (CDR X-LST) A)))))
    (DEFTHM EVL2-CONSTRAINT-6
      (IMPLIES (AND (NOT (CONSP X))
                    (NOT (SYMBOLP X)))
               (EQUAL (EVL2 X A) NIL)))
    (DEFTHM EVL2-CONSTRAINT-7
      (IMPLIES (AND (CONSP X) (EQUAL (CAR X) 'F))
               (EQUAL (EVL2 X A) ; changed f to f2 just below
                      (F2 (EVL2 (CADR X) A)))))
    (DEFTHM EVL2-CONSTRAINT-8
      (IMPLIES (AND (CONSP X) (EQUAL (CAR X) 'F2))
               (EQUAL (EVL2 X A)
                      (F2 (EVL2 (CADR X) A)))))
    (DEFTHM EVL2-CONSTRAINT-9
      (IMPLIES (AND (CONSP X) (EQUAL (CAR X) 'G))
               (EQUAL (EVL2 X A) (G))))
    (DEFTHM EVL2-CONSTRAINT-10
      (IMPLIES (AND (CONSP X) (EQUAL (CAR X) 'G2))
               (EQUAL (EVL2 X A) (G2)))))

  (defthm f2-t
     (equal (f2 x) t)
     :hints (("Goal" :by (:functional-instance
                          f-t
                          (f f2)
                          (evl evl2)
                          (evl-list evl2-list)))))

  (defthm bug-implies-nil
     nil
     :hints (("Goal" :use ((:instance f2-t (x t)))))
     :rule-classes nil)
 })

 <p>Finally, we also require that no function has an attachment (see @(see
 defattach)) that is both ancestral in the evaluator and also ancestral in the
 meta or clause-processor functions.  (If you don't use @(tsee defattach) or
 @(tsee apply$) &mdash; more specifically, @(see warrant)s &mdash; then you can
 ignore this condition.)  Without this restriction, the following events prove
 @('nil').</p>

 @({
  (in-package "ACL2")
  (defstub f () t)
  (defevaluator evl evl-list
    ((f)))
  (defun my-meta-fn (x)
    (if (equal x '(f))
        (list 'quote (f))
      x))
  (defthm my-meta-fn-correct
    (equal (evl x a)
           (evl (my-meta-fn x) a))
    :rule-classes ((:meta :trigger-fns (f))))
  (defun constant-nil ()
    (declare (xargs :guard t))
    nil)
  (defattach f constant-nil)
  (defthm f-is-nil
  ; proved using my-meta-fn-correct
    (equal (f) nil)
    :rule-classes nil)
  (defthm contradiction
    nil
    :hints (("Goal" :use ((:functional-instance
                           f-is-nil
                           (f (lambda () t))))))
    :rule-classes nil)
 })

 <p>Here is an example that doesn't use @(tsee defattach) explicitly, but uses
 @(see warrant)s, which essentially have attachments so that every call of a
 warrant evaluates to @('T').  As for the preceding example, these events
 succeed if we remove the restriction stated above about common ancestors of
 the evaluator and the meta or clause-processor function.</p>

 @({
 (in-package "ACL2")

 (include-book "projects/apply/top" :dir :system)

 (defevaluator evl evl-list
   ((apply$ fn args)))

 (encapsulate
   ()
   (local (defun$ f () (declare (xargs :guard t)) t))
   (local (defun my-meta-fn (x)
            (if (and (equal x '(apply$ 'f 'nil))
                     (apply$-warrant-f))
                *t*
              x)))
   (local (defthm my-meta-fn-correct
            (equal (evl x a)
                   (evl (my-meta-fn x) a))
            :rule-classes ((:meta :trigger-fns (apply$)))))
   (defthm unwarranted-fact-about-quote-f
     (equal (apply$ 'f nil) t)
     :rule-classes nil))

 (defun$ f () nil)

 (defthm apply$-warrant-f-false
   (not (apply$-warrant-f))
   :hints (("Goal" :use unwarranted-fact-about-quote-f))
   :rule-classes nil)

 ; But apply$-warrant-f is a function with no non-trivial constraint.

 (defthm contradiction
   nil
   :hints
   (("Goal"
     :use (:functional-instance
           apply$-warrant-f-false
           (apply$-warrant-f (lambda () t))
           (apply$-userfn (lambda (fn args) nil))
           (badge-userfn (lambda (fn) '(APPLY$-BADGE 0 1 . T))))))
   :rule-classes nil)
 })

 <p>To see why this restriction is sufficient, see a comment in the ACL2 source
 code entitled ``; Essay on Correctness of Meta Reasoning.''</p>

 <p>One can sometimes work around this restriction; see @(see
 transparent-functions).</p>")

(defxdoc evenp
  :parents (numbers acl2-built-ins)
  :short "Test whether an integer is even"
  :long "<p>@('(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.</p>

 <p>The @(see guard) for @('evenp') requires its argument to be an integer.</p>

 <p>@('Evenp') is a Common Lisp function.  See any Common Lisp documentation
 for more information.</p>

 @(def evenp)")

(defxdoc evens
  :parents (lists acl2-built-ins)
  :short "The even-indexed members of a list"
  :long "<p>The call @('(evens x)') returns the restriction of the true-list
 @('x') to its even-indexed members (with zero-based indexing).  Note that if
 @('x') is a list @('(k1 a1 k2 a2 ... kn an)') that satisfies the predicate
 @(tsee keyword-value-listp), then @('(evens x)') lists the keys @('ki') of
 @('x').  Thus, the following is a theorem.</p>

 @({
  (thm (iff (keyword-value-listp l)
            (and (true-listp l)
                 (evenp (len l))
                 (keyword-listp (evens l))))
       :hints (("Goal" :induct (keyword-value-listp l))))
 })

 @(def evens)")

(defxdoc events
  :parents (acl2)
  :short "Functions that extend the logic"
  :long "<p>Any extension of the syntax of ACL2 (i.e., the definition of a new
 constant or macro), the axioms (i.e., the definition of a function), or the
 rule database (i.e., the proof of a theorem), constitutes a logical ``event.''
 Events change the ACL2 logical world (see @(see world)).  Indeed, the only way
 to change the ACL2 @(see world) is via the successful evaluation of an event
 function.  Every time the @(see world) is changed by an event, a landmark is
 left on the @(see world) and it is thus possible to identify the @(see world)
 ``as of'' the evaluation of a given event.  An event may introduce new logical
 names.  Some events introduce no new names (e.g., @(tsee verify-guards)), some
 introduce exactly one (e.g., @(tsee defmacro) and @(tsee defthm)), and some
 may introduce many (e.g., @(tsee encapsulate) ).</p>

 <p>ACL2 typically completes processing of an event by printing a @(see
 summary).  Unless proofs are skipped (see @(see ld-skip-proofsp)) or summary
 output is inhibited (see @(see set-inhibit-output-lst)), information about the
 proof attempt (if any) is printed that includes a list of rules used, a
 summary of warnings, and the number of ``prover steps'' (if any; see @(see
 with-prover-step-limit)).  A breakdown of the time used is also printed, which
 by default is runtime (cpu time), but can be changed to realtime (wall clock
 time); see @(see get-internal-time).</p>

 <p>See @(see embedded-event-form) for a discussion of events permitted in
 @(see books).</p>")

(defxdoc evisc-table
  :parents (events)
  :short "Support for abbreviated output"
  :long "<p>The @('evisc-table') is an ACL2 table (see @(see table)) whose
 purpose is to modify the print representations of specified non-@('nil')
 objects.  When a key (some object) is associated with a string value, then
 that string is printed instead of that key (as an abbreviation).  For example,
 the following log shows how to abbreviate the key @('(a b c)') with the token
 @('<my-abc-list>').</p>

 @({
  ACL2 !>(table evisc-table '(a b c) "<my-abc-list>")

  Summary
  Form:  ( TABLE EVISC-TABLE ...)
  Rules: NIL
  Warnings:  None
  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
   EVISC-TABLE
  ACL2 !>'(a b c)
  <my-abc-list>
  ACL2 !>'(4 5 a b c)
  (4 5 . <my-abc-list>)
  ACL2 !>
 })

 <p>Every value in this @(see table) must be either a string or @('nil'), where
 @('nil') eliminates any association of the key with an abbreviation.
 Continuing with the log above:</p>

 @({
  ACL2 !>(table evisc-table '(a b c) nil)

  Summary
  Form:  ( TABLE EVISC-TABLE ...)
  Rules: NIL
  Warnings:  None
  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
   EVISC-TABLE
  ACL2 !>'(a b c)
  (A B C)
  ACL2 !>'(4 5 a b c)
  (4 5 A B C)
  ACL2 !>
 })

 <p>It can be particularly helpful to use this table to abbreviate a constant
 introduced by @(tsee defconst) by prefixing the constant name with
 @('"#."'), as we now describe.  Consider first the following example.</p>

 @({
  (defconst *abc* '(1 2 3 4 5 6 7 8))
  (table evisc-table *abc*
    (concatenate 'string "#." (symbol-name '*abc*)))
 })

 <p>Then the constant @('*abc*') is printed as follows &mdash; very helpful if
 its associated structure is significantly larger than the 8-element list of
 numbers shown above!</p>

 @({
  ACL2 !>*abc*
  #.*ABC*
  ACL2 !>
 })

 <p>What's more, the ACL2 reader will replace @('#.*C*'), where @('*C*') is
 defined by @(tsee defconst), by its value, regardless of @('evisc-table'); see
 @(see sharp-dot-reader).  Continuing with the example above, we have:</p>

 @({
  ACL2 !>(cdr (quote #.*ABC*))
  (2 3 4 5 6 7 8)
  ACL2 !>
 })

 <p>Of course, more care needs to be taken if packages are involved (see @(see
 defpkg)), as we now illustrate.</p>

 @({
  ACL2 !>(defpkg "FOO" nil)

  Summary
  Form:  ( DEFPKG "FOO" ...)
  Rules: NIL
  Warnings:  None
  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
   "FOO"
  ACL2 !>(defconst foo::*a* '(1 2 3))

  Summary
  Form:  ( DEFCONST FOO::*A* ...)
  Rules: NIL
  Warnings:  None
  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
   FOO::*A*
  ACL2 !>(table evisc-table foo::*a* "#.foo::*a*")

  Summary
  Form:  ( TABLE EVISC-TABLE ...)
  Rules: NIL
  Warnings:  None
  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
   EVISC-TABLE
  ACL2 !>foo::*a*
  #.foo::*a*
  ACL2 !>'#.foo::*a*
  #.foo::*a*
  ACL2 !>(cdr '#.foo::*a*)
  (2 3)
  ACL2 !>
 })

 <p>We conclude by an example showing some extra care that may be important to
 consider taking.  We start with:</p>

 @({
  (defconst |*BaR*| '(3 4))
 })

 <p>Then the following works just fine; but try it without the extra code for
 the @('may-need-slashes') case and you'll see that the sharp-dot printing is
 missing.  First:</p>

 @({
  (table evisc-table
         |*BaR*|
         (let ((x (symbol-name '|*BaR*|)))
           (if (may-need-slashes x)
               (concatenate 'string "#.|" x "|")
             (concatenate 'string "#." x))))
 })

 <p>Then:</p>

 @({
  ACL2 !>|*BaR*|
  #.|*BaR*|
  ACL2 !>
 })

 <p>The examples above illustrate how the @('evisc-table') is used when
 printing evaluation results.  More generally, that @(see table) is used when
 @(tsee fmt) (or a related function such as @(tsee fms)) prints an object using
 @('~x') @('~X'), @('~y'), @('~Y'), @('~f'), or @('~F').</p>")

(defxdoc evisc-tuple
  :parents (io)
  :short "Control suppression of details when printing"
  :long "<p>ACL2 output is generally printed in full.  However, ACL2 can be
 directed to abbreviate, or ``eviscerate'', objects before printing them.  To
 ``eviscerate'' an object we replace certain substructures within it by strings
 that are printed in their stead.  Such replacement is made relative to a
 so-called ``evisc-tuple'', which has four components: @('(evisc-tuple
 print-level print-length alist hiding-cars)') is the same as the value of
 @('(list alist print-level print-length hiding-cars)'), and the components are
 used as follows (with priority order as discussed below).  The @('alist')
 component is used to replace any substructure occurring as a key by the
 corresponding string.  The @('print-level') and @('print-length') are
 analogous to Common Lisp variables @('*print-level*') and @('*print-length*'),
 respectively, and cause replacement of substructures deeper than
 @('print-level') by `@('#')' and those longer than @('print-length') by
 `@('...')'.  Finally, any @(tsee consp) @('x') that starts with one of the
 symbols in @('hiding-cars') is printed as @('<hidden>').</p>

 <p>The following example illustrates the use of an evisc-tuple that limits the
 print-level to 3 &mdash; only three descents into list structures are
 permitted before replacing a subexpression by `@('#')' &mdash; and limits the
 print-length to 4 &mdash; only the first four elements of any list structure
 will be printed before replacing its tail by `@('...')'.</p>

 @({
  ACL2 !>(fms "~x0~%"
              (list (cons #\0 '((a b ((c d)) e f g) u v w x y)))
              *standard-co*
              state
              (evisc-tuple 3 4 nil nil))

  ((A B (#) E ...) U V W ...)
  <state>
  ACL2 !>
 })

 <p>Notice that it is impossible to read the printed value back into ACL2,
 since there is no way for the ACL2 reader to interpret `@('#')' or `@('...')'.
 To solve this problem, see @(see set-iprint).</p>

 <p>In the above example we pass an evisc-tuple explicitly to a printing
 function, in this case, @(tsee fms) (see @(see fmt)).  But ACL2 also does its
 own printing, for example during a proof attempt.  There are global
 evisc-tuples that control ACL2's printing; see @(see set-evisc-tuple) and see
 @(see without-evisc).</p>")

(defxdoc eviscerate-hide-terms
  :parents (io)
  :short "To print @('(hide ...)') as @('<hidden>')"
  :long "@({
  Example:
  (assign eviscerate-hide-terms t)
  (assign eviscerate-hide-terms nil)
 })

 <p>@('Eviscerate-hide-terms') is a @(tsee state) global variable whose value
 is either @('t') or @('nil').  The variable affects how terms are displayed by
 default (but not if you have set the term-evisc-tuple to other than its
 default; see @(see set-evisc-tuple)).  If @('t'), terms of the form @('(hide
 ...)')  are printed as @('<hidden>').  Otherwise, they are printed
 normally.</p>")

(defxdoc example-induction-scheme-binary-trees
  :parents (introduction-to-the-theorem-prover)
  :short "Induction on binary trees"
  :long "<p>See @(see logic-knowledge-taken-for-granted-inductive-proof) for an
 explanation of what we mean by the induction <i>suggested</i> by a recursive
 function or a term.</p>

 <p><b>Classical Induction on Binary Trees</b>: To prove @('(p x)'), for all
 @('x'), by classical induction on binary tree structures, prove each of the
 following:</p>

 <code>
 <i>Base Case</i>:
 (implies (atom x) (p x))
 </code>

 <code>
 <i>Induction Step</i>:
 (implies (and (not (atom x))
               (p (car x))
               (p (cdr x)))
          (p x))
 </code>

 <p>An argument analogous to that given in @(see
 example-induction-scheme-on-lists) should convince you that @('(p x)') holds
 for every object.</p>

 <p>A function that suggests this induction is:</p>

 @({
  (defun flatten (x)
    (if (atom x)
        (list x)
        (app (flatten (car x))
             (flatten (cdr x))))).
 })")

(defxdoc example-induction-scheme-down-by-2
  :parents (introduction-to-the-theorem-prover)
  :short "Induction downwards 2 steps at a time"
  :long "<p>See @(see logic-knowledge-taken-for-granted-inductive-proof) for an
 explanation of what we mean by the induction <i>suggested</i> by a recursive
 function or a term.</p>

 <p><b>Classical Induction on Natural Numbers Preserving Parity</b>: Here is
 another way to decompose natural numbers.  To prove @('(p n)'), for all
 @('n'), prove each of the following:</p>

 <code>
 <i>Base Case 1</i>:
 (implies (zp n) (p n))
 </code>

 <code>
 <i>Base Case 2</i>:
 (implies (equal n 1) (p n))
 </code>

 <code>
 <i>Induction Step</i>:
 (implies (and (not (zp n))
               (not (equal n 1))
               (p (- n 2)))
          (p n))
 </code>

 <p>Base Case 1 establishes that @('p') holds for @('0') (and all objects other
 than positive naturals).</p>

 <p>Base Case 2 establishes that @('p') holds for @('1').</p>

 <p>The Induction Step establishes that if @('n') is a natural number greater
 than @('1'), and if @('p') holds for @('n')-2, then @('p') holds for
 @('n').</p>

 <p>Note that we have thus proved that @('(p n)') holds, for all @('n').  For
 example, @('(p -7)'), @('(p 'abc)'), and @('(p 0)') are all established by
 Base Case 1.  @('(p 1)') is established by Base Case 2.  @('(p 2)') is
 established from @('(p 0)') and the Induction Step.  Think about it!  @('(p
 3)') is established form @('(p 1)') and the Induction Step, etc.</p>

 <p>A function that suggests this induction is:</p>

 @({
  (defun parity (n)
    (if (zp n)
        'even
        (if (equal n 1)
            'odd
            (parity (- n 2))))).
 })")

(defxdoc example-induction-scheme-nat-recursion
  :parents (introduction-to-the-theorem-prover)
  :short "Induction on natural numbers"
  :long "<p>See @(see logic-knowledge-taken-for-granted-inductive-proof) for an
 explanation of what we mean by the induction <i>suggested</i> by a recursive
 function or a term.</p>

 <p><b>Classical Induction on Natural Numbers</b>: Induction is familiar in the
 arithmetic setting.  To prove @('(p n)'), for all @('n'), by classical
 induction on the construction of the natural numbers, prove each of the
 following:</p>

 <code>
 <i>Base Case</i>:
 (implies (zp n) (p n))
 </code>

 <code>
 <i>Induction Step</i>:
 (implies (and (not (zp n))
               (p (- n 1)))
          (p n))
 </code>

 <p>The Base Case establishes that @('p') holds for @('0').  In fact, because
 of the definition of @(tsee zp) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>, it
 establishes that @('(p n)') holds when @('n') is @('0') and it holds when
 @('n') is not a natural number.</p>

 <p>The Induction Step establishes that if @('n') is a natural number other
 than @('0'), and if @('p') holds for @('n')-1, then @('p') holds for @('n').
 The hypothesis @('(p (- n 1))') above is called the <i>induction
 hypothesis</i>.</p>

 <p>A function that suggests this induction is</p>

 @({
  (defun nat-recursion (n)
    (if (zp n)
        n
        (nat-recursion (- n 1))))
 })

 <p>Similarly, the term @('(fact n)') suggests this induction if @('fact') is
 defined:</p>

 @({
   (defun fact (k)
    (if (zp k)
        1
        (* k (fact (- k 1))))).
 })

 <p>even though the formal parameter of this definition of @('fact') is @('k'),
 not @('n').</p>")

(defxdoc example-induction-scheme-on-lists
  :parents (introduction-to-the-theorem-prover)
  :short "Induction on lists"
  :long "<p>See @(see logic-knowledge-taken-for-granted-inductive-proof) for an
 explanation of what we mean by the induction <i>suggested</i> by a recursive
 function or a term.</p>

 <p><b>Classical Induction on Lists</b>: To prove @('(p x)'), for all @('x'),
 by classical induction on the linear list structure, prove each of the
 following:</p>

 <code>
 <i>Base Case</i>:
 (implies (endp x) (p x))
 </code>

 <code>
 <i>Induction Step</i>:
 (implies (and (not (endp x))
               (p (cdr x)))
          (p x))
 </code>

 <p>An argument analogous to that given for natural numbers, @(see
 example-induction-scheme-nat-recursion), establishes @('(p x)') for every
 @('x').  For example, @('(p -7)'), @('(p 'abc)'), and @('(p nil)') are all
 established by the Base Case.  @('(p '(Friday))') follows from @('(p nil)'),
 given the Induction Step.  That sentence bears thinking about!  Think about
 it!  Similarly, @('(p '(Yellow))') holds for the same reason.  @('(p
 '(Thursday Friday))') follows from @('(p '(Friday))') and the Induction Step,
 etc.</p>

 <p>A function that suggests this induction is</p>

 @({
  (defun app (x y)
    (if (endp x)
        y
        (cons (car x)
              (app (cdr x) y)))).
 })")

(defxdoc example-induction-scheme-on-several-variables
  :parents (introduction-to-the-theorem-prover)
  :short "Induction on several variables"
  :long "<p>See @(see logic-knowledge-taken-for-granted-inductive-proof) for an
 explanation of what we mean by the induction <i>suggested</i> by a recursive
 function or a term.</p>

 <p><b>Induction on Several Variables</b> To @('(p n x)') for all @('n') and
 all @('x'), prove each of the following:</p>

 <code>
 <i>Base Case 1</i>:
 (implies (endp x)
          (p n x))
 </code>

 <code>
 <i>Base Case 2</i>:
 (implies (and (not (endp x))
               (zp n))
          (p n x))
 </code>

 <code>
 <i>Induction Step</i>:
 (implies (and (not (endp x))
               (not (zp n))
               (p (- n 1) (cdr x)))
          (p n x))
 </code>

 <p>A function that suggests this induction is</p>

 @({
  (defun nth (n x)
    (if (endp x)
        nil
        (if (zp n)
            (car x)
            (nth (- n 1) (cdr x))))).
 })")

(defxdoc example-induction-scheme-upwards
  :parents (introduction-to-the-theorem-prover)
  :short "Induction upwards"
  :long "<p>See @(see logic-knowledge-taken-for-granted-inductive-proof) for an
 explanation of what we mean by the induction <i>suggested</i> by a recursive
 function or a term.</p>

 <p><b>Induction Upwards</b>: To @('(p i max)') for all @('i') and all
 @('max'), prove each of the following:</p>

 <code>
 <i>Base Case</i>:
 (implies (not (and (natp i)
                    (natp max)
                    (&lt; i max)))
          (p i max))
 </code>

 <code>
 <i>Induction Step</i>:
 (implies (and  (natp i)
                (natp max)
                (&lt; i max)
                (p (+ i 1) max))
          (p i max))
 </code>

 <p>Note that the induction hypothesis is about an @('i') that is <i>bigger</i>
 than the @('i') in in the conclusion.  In induction, as in recursion, the
 sense of one thing being ``smaller'' than another is determined by an
 arbitrary measure of all the variables, not the magnitude or extent of some
 particular variable.</p>

 <p>A function that suggests this induction is shown below.  ACL2 has to be
 told the measure, namely the difference between @('max') and @('i') (coerced
 to a natural number to ensure that the measure is an ordinal).</p>

 @({
  (defun count-up (i max)
    (declare (xargs :measure (nfix (- max i))))
    (if (and (natp i)
             (natp max)
             (< i max))
        (cons i (count-up (+ 1 i) max))
        nil)).
 })")

(defxdoc example-induction-scheme-with-accumulators
  :parents (introduction-to-the-theorem-prover)
  :short "Induction scheme with accumulators"
  :long "<p>See @(see logic-knowledge-taken-for-granted-inductive-proof) for an
 explanation of what we mean by the induction <i>suggested</i> by a recursive
 function or a term.</p>

 <p>To prove @('(p x a)') for all @('x') and all @('a'), prove each of the
 following:</p>

 <code>
 <i>Base Case</i>:
 (implies (endp x)
          (p x a))
 </code>

 <code>
 <i>Induction Step</i>:
 (implies (and (not (endp x))
               (p (cdr x) (cons (car x) a)))
          (p x a))
 </code>

 <p>Note that in the induction hypothesis we assume @('p') for a smaller @('x')
 but a larger @('a').  In fact, we could include as many induction hypotheses
 as we want and use any terms we want in the @('a') position as long as the
 @('x') position is occupied by a smaller term.</p>

 <p>A function that suggests this particular induction is shown below.</p>

 @({
  (defun rev1 (x a)
    (if (endp x)
        a
        (rev1 (cdr x) (cons (car x) a)))).
 })

 <p>A function that suggests a similar induction in which three induction
 hypotheses are provided, one in which the @('a') position is occupied by
 @('(cons (car x) a)'), another in which the @('a') position is occupied by
 some arbitrary term @('b'), and a third in which the @('a') position is
 occupied by @('a'), is suggested by the term @('(rev1-modified x a b)')
 where</p>

 @({
  (defun rev1-modified (x a b)
    (if (endp x)
        (list x a b)
        (list (rev1-modified (cdr x) (cons (car x) a) b)
              (rev1-modified (cdr x) b b)
              (rev1-modified (cdr x) a b))))
 })

 <p>Remember that the value of this term or function is irrelevant to the
 induction suggested.  Because ACL2's definitional principle insists that all
 the formal parameters play a role in the computation (at least syntactically),
 it is common practice when defining functions for their induction schemes to
 return the @('list') of all the formals (to ensure all variables are involved)
 and to combine recursive calls on a given branch with @('list') (to avoid
 introducing additional case analysis as would happen if @('and') or @('or') or
 other propositional functions are used).</p>

 <p>If you tried to prove @('(p x a)') and suggested the induct hint
 @('(rev1-modified x a (fact k))'), as by</p>

 @({
  (thm (p x a)
       :hints (("Goal" :induct (rev1-modified x a (fact k)))))
 })

 <p>the inductive argument would be:</p>

 <code>
 <i>Base Case</i>:
 (implies (endp x)
          (p x a))
 </code>

 <code>
  <i>Inductive Step</i>:
  (implies (and (not (endp x))
                (p (cdr x) (cons (car x) a))
                (p (cdr x) (fact k))
                (p (cdr x) a))
           (p x a))
  </code>")

(defxdoc example-induction-scheme-with-multiple-induction-steps
  :parents (introduction-to-the-theorem-prover)
  :short "Induction scheme with more than one induction step"
  :long "<p>See @(see logic-knowledge-taken-for-granted-inductive-proof) for an
 explanation of what we mean by the induction <i>suggested</i> by a recursive
 function or a term.</p>

 <p><b>Several Induction Steps</b>: To @('(p x i a)') for all @('x'), @('i'),
 and @('a'), prove each of the following:</p>

 <code>
 <i>Base Case 1</i>:
 (implies (zp i)
          (p x i a))
 </code>

 <code>
 <i>Induction Step 1</i>:
 (implies (and (not (zp i))
               (equal (parity i) 'even)
               (p (* x x)
                  (floor i 2)
                  a))
          (p x i a))
 </code>

 <code>
 <i>Induction Step 2</i>:
 (implies (and (not (zp i))
               (not (equal (parity i) 'even))
               (p x
                  (- i 1)
                  (* x a)))
          (p x i a))
 </code>

 <p>A function that suggests this induction is the binary exponentiation
 function for natural numbers.</p>

 @({
  (defun bexpt (x i a)
    (cond ((zp i) a)
          ((equal (parity i) 'even)
           (bexpt (* x x)
                  (floor i 2)
                  a))
          (t (bexpt x
                    (- i 1)
                    (* x a)
                    )))).
 })

 <p>In order to admit this function it is necessary to know that @('(floor i
 2)') is smaller than @('i') in the case above.  This can be proved if the
 community book @('"arithmetic-5/top"') has been included from the ACL2
 system directory, i.e.,</p>

 @({
  (include-book "arithmetic-5/top" :dir :system)
 })

 <p>should be executed before defining @('bexpt').</p>")

(defxdoc example-inductions
  :parents (introduction-to-the-theorem-prover)
  :short "Some examples of induction schemes in ACL2"
  :long "<p>Here are some pages illustrating various induction schemes
 suggested by recursive functions.</p>

 <p><b>Classical Induction on Natural Numbers</b>: see @(see
 example-induction-scheme-nat-recursion).</p>

 <p><b>Induction Preserving Even/Odd Parity</b> or<br></br>

 <b>Induction Downwards by 2</b> or <br></br>

 <b>Induction with Multiple Base Cases</b>: see @(see
 example-induction-scheme-down-by-2) for an induction in which the induction
 hypothesis decreases the induction variable by an amount other than 1.  This
 illustrates that the induction hypothesis can be about whatever term or terms
 are needed to explain how the formula recurs.  The example also illustrates an
 induction with more than one Base Case.</p>

 <p><b>Classical Induction on Lists</b>: see @(see
 example-induction-scheme-on-lists) for an induction over linear lists, in
 which we inductively assume the conjecture for @('(cdr x)') and prove it for
 @('x').  It doesn't matter whether the list is @('nil')-terminated or not; the
 Base Case addresses all the possibilities.</p>

 <p><b>Classical Induction on Binary (Cons) Trees</b>: see @(see
 example-induction-scheme-binary-trees) for an induction over the simplest form
 of binary tree.  Here the Induction Step provides two hypotheses, one about
 the left subtree and one about the right subtree.</p>

 <p><b>Induction on Several Variables</b>: see @(see
 example-induction-scheme-on-several-variables) for an induction in which
 several variables participate in the case analysis and induction
 hypotheses.</p>

 <p><b>Induction Upwards</b>: see @(see example-induction-scheme-upwards) for
 an induction scheme in which the induction hypothesis is about something
 ``bigger than'' the induction conclusion.  This illustrates that the sense in
 which the hypothesis is about something ``smaller'' than the conclusion is
 determined by a measure of all the variables, not the magnitude or extent of
 some single variable.</p>

 <p><b>Induction with Auxiliary Variables</b> or<br></br>

 <b>Induction with Accumulators</b>: see @(see
 example-induction-scheme-with-accumulators) for an induction scheme in which
 one variable ``gets smaller'' but another is completely arbitrary.  Such
 schemes are common when dealing with tail-recursive functions that accumulate
 partial results in auxiliary variables.  This example also shows how to
 provide several arbitrary terms in a non-inductive variable of a scheme.</p>

 <p><b>Induction with Multiple Induction Steps</b>: see @(see
 example-induction-scheme-with-multiple-induction-steps) for an induction in
 which we make different inductive hypotheses depending on which case we're in.
 This example also illustrates the handling of auxiliary variables or
 accumulators.</p>")

(defxdoc executable-counterpart
  :parents (rule-classes)
  :short "A rule for computing the value of a function"
  :long "<p>This topic is about a type of @(see rune) that controls evaluation
 using the executable-counterpart of a function.  For discussion of
 executable-counterparts of functions, see @(see evaluation).</p>

 @({
  Example:
  (:executable-counterpart length)
 })

 <p>which may be abbreviated in @(see theory) expressions in either of the
 following two ways (see @(see rune)).</p>

 @({
  (:e length)
  (length)
 })

 <p>Every @(tsee defun) introduces at least two rules used by the theorem
 prover.  Suppose @('fn') is the name of a @(tsee defun)'d function.  Then
 @('(:definition fn)') is the rune (see @(see rune)) naming the rule that
 allows the simplifier to replace calls of @('fn') by its instantiated body.
 @('(:executable-counterpart fn)') is the @(see rune) for the rule for how to
 evaluate the function on known constants.</p>

 <p>When typing @(see theories) it is convenient to know that @('(fn)') is a
 runic designator that denotes @('(:executable-counterpart fn)').  See @(see
 theories).</p>

 <p>If @('(:executable-counterpart fn)') is @(see enable)d, then when
 applications of @('fn') to known constants are seen by the simplifier they are
 computed out by executing the Common Lisp code for @('fn') (with the
 appropriate handling of @(see guard)s).  Suppose @('fact') is defined as the
 factorial function.  If the executable-counterpart @(see rune) of @('fact'),
 @('(:executable-counterpart fact)'), is @(see enable)d when the simplifier
 encounters @('(fact 12)'), then that term will be ``immediately'' expanded to
 @('479001600').  Note that even if subroutines of @('fn') have disabled
 executable-counterparts, @('fn') will call their Lisp code nonetheless: once
 an executable-counterpart function is applied, no subsidiary enable checks are
 made.</p>

 <p>Such one-step expansions are sometimes counterproductive because they
 prevent the anticipated application of certain lemmas about the subroutines of
 the expanded function.  Such computed expansions can be prevented by disabling
 the executable-counterpart @(see rune) of the relevant function.  For example,
 if @('(:executable-counterpart fact)') is @(see disable)d, @('(fact 12)') will
 not be expanded by computation.  In this situation, @('(fact 12)') may be
 rewritten to @('(* 12 (fact 11))'), using the rule named @('(:definition
 fact)'), provided the system's heuristics permit the introduction of the term
 @('(fact 11)').  Note that lemmas about multiplication may then be applicable
 (while such lemmas would be inapplicable to @('479001600')).  In many proofs
 it is desirable to @(see disable) the executable-counterpart @(see rune)s of
 certain functions to prevent their expansion by computation.  See @(see
 executable-counterpart-theory).</p>

 <p>Finally: What do we do about functions that are ``constrained'' rather than
 defined, such as the following?  (See @(see encapsulate).)</p>

 @({
  (encapsulate (((foo *) => *))
               (local (defun foo (x) x)))
 })

 <p>Does @('foo') have an executable-counterpart?  Yes: since the vast majority
 of functions have sensible executable-counterparts, it was decided that
 <b>all</b> functions, even such ``constrained'' ones, have
 executable-counterparts.  We essentially ``trap'' when such calls are
 inappropriate.  Thus, consider for example:</p>

 @({
  (defun bar (x)
    (if (rationalp x)
        (+ x 1)
      (foo x)))
 })

 <p>If the term @('(bar '3)') is encountered by the ACL2 rewriter during a
 proof, and if the @(':executable-counterpart') of @('bar') is @(see enable)d,
 then it will be invoked to reduce this term to @(''4').  However, if the term
 @('(bar 'a)') is encountered during a proof, then since @(''a') is not a
 @(tsee rationalp) and since the @(':executable-counterpart') of @('foo') is
 only a ``trap,'' then this call of the @(':executable-counterpart') of
 @('bar') will result in a ``trap.'' In that case, the rewriter will return the
 term @('(hide (bar 'a))') so that it never has to go through this process
 again.  See @(see hide).</p>")

(defxdoc executable-counterpart-theory
  :parents (theories theory-functions)
  :short "@(csee Executable-counterpart) rules as of logical name"
  :long "@({
  Examples:
  (executable-counterpart-theory :here)
  (executable-counterpart-theory 'lemma3)
 })

 <p>See @(see logical-name).</p>

 @({
  General Form:
  (executable-counterpart-theory logical-name)
 })

 <p>Returns the theory containing all the @(':')@(tsee executable-counterpart)
 @(see rune)s, whether @(see enable)d or not, that existed immediately after
 @(tsee logical-name) was introduced.  See the documentation for @(see
 theories), @(see logical-name), @(see executable-counterpart) and @(tsee
 function-theory).</p>

 <p>You may experience a fencepost problem in deciding which logical name to
 use.  @(tsee Deflabel) can always be used to mark unambiguously for future
 reference a particular point in the development of your theory.  The order of
 @(see events) in the vicinity of an @(tsee encapsulate) is confusing.  See
 @(see encapsulate).</p>

 <p>This ``function'' is actually a macro that expands to a term mentioning the
 single free variable @(tsee world).  When theory expressions are evaluated by
 @(tsee in-theory) or the @(':')@(tsee in-theory) hint, @(tsee world) is bound
 to the current ACL2 @(see world).</p>")

(defxdoc exists
  :parents (defun-sk)
  :short "Existential quantifier"
  :long "<p>The symbol @('exists') (in the ACL2 package) represents existential
 quantification in the context of a @(tsee defun-sk) form.  See @(see defun-sk)
 and see @(see forall).</p>

 <p>See @(see quantifiers) for an example illustrating how the use of
 recursion, rather than explicit quantification with @(tsee defun-sk), may be
 preferable.</p>")

(defxdoc exit
  :parents (good-bye)
  :short "Quit entirely out of Lisp"
  :long "<p>Same as @(tsee good-bye).</p>")

(defxdoc exit-boot-strap-mode
  :parents (history)
  :short "The end of pre-history"
  :long "<p>@('Exit-boot-strap-mode') is the last step in creating the ACL2
 @(see world) in which the user lives.  It has @(see command) number @('0').
 @(see Command)s before it are part of the system initialization and extend all
 the way back to @(':')@(tsee min).  @(see Command)s after it are those of the
 user.</p>

 <p>@('Exit-boot-strap-mode') is a Common Lisp function but not an ACL2
 function.  It is called when every @(tsee defconst), @(tsee defun), etc., in
 our source code has been processed under ACL2 and the @(see world) is all but
 complete.  @('exit-boot-strap-mode') has only one job: to signal the
 completion of the boot-strapping.</p>")

(defxdoc explain-giant-lambda-object
  :parents (apply$)
  :short "print data related to a large lambda object"
  :long "<p>Translate will signal an error if it encounters an
  &ldquo;excessively large&rdquo; @(tsee lambda) object.  These objects are so
  large they are difficult to comprehend when printed.  So the error message
  directs you to this documentation topic.  To see the @('lambda') object that
  caused the error, execute</p>

  @({
  (explain-giant-lambda-object)
  })

  <p>The rest of this documentation topic explains why we detect these objects
  and what you can do about them.</p>

  <p>When a @(tsee lambda) object is translated we @(tsee hons-copy) it
  so that it is uniquely represented.  This speeds up the performance of the
  compiled @('lambda') cache (see @(tsee print-cl-cache)).</p>

  <p>However, if the number of conses in the @('lambda') object is greater than
  or equal to @('(lambda-object-count-max-val)'), we cause an error.  If this
  error has been signaled in your session we recommend that you evaluate
  @('(explain-giant-lambda-object)'), which will tell you more about the
  excessively large @('lambda') object.  The current value of
  @('(lambda-object-count-max-val)') is 200,000.  For reference, the largest
  function definition in the ACL2 sources (as of Version  8.6) is the @(tsee
  mutual-recursion) event defining @('rewrite') and its 51 mutually recursive
  subfunctions.  The total number of conses in that clique is 14,656.</p>

  <p>There are generally two ways excessively large @('lambda') objects come
  into existence: (1) they are generated automatically, as by macros,
  functions, or @(tsee make-event), or (2) you wrote a small @('lambda') object
  but used a big quoted constant in it.</p>

  <p>(1) If the offending @('lambda') object was built mechanically, we
  recommend that you redefine the generation process so that it introduces a
  named function.  For example, suppose the @('lambda') object sketched below
  is excessively large.</p>

  @({
  (lambda (x y)
    (if (eq x 'FOO1)
        (my-foo1 y)
        (if (eq x 'FOO2)
            (my-foo2 y)
            ...)))
  })

  <p>Then perhaps instead of generating that object you could generate
  the definition</p>

  @({
  (defun my-big-switch (x y)
    (if (eq x 'FOO1)
        (my-foo1 y)
        (if (eq x 'FOO2)
            (my-foo2 y)
            ...)))
  })

  <p>And then use the quite small @('(lambda$ (x y) (my-big-switch x y))') in
  place of the offending @('lambda') object.  Of course, this is not always
  easy to carry out, since it would also require calling @(tsee defwarrant) on
  @('my-big-switch') and providing that warrant as a hypothesis to any theorem
  involving the new @('lambda') object.</p>

  <p>(2) If the offending @('lambda') object just contains large quoted
  constants perhaps you can bind a variable to the large value outside of the
  @('lambda') object and pass that variable into the @('lambda') object in a
  new formal.</p>

  <p>For example, suppose the term @('(regression-suite)') returns is a list of
  pairs of sample inputs and correct output for testing some software system
  whose binary machine code is in the constant declared below.</p>

  @({
  (defconst *system*
    '(#x488b55f0
      #x31ff
      #xff142570081050
      #xf84995b0000
      #xf645f801
      #xf8573100000
      #x807df019
      ...))
  })

  <p>Then we might wish to execute something like the following.</p>

  @({
  ACL2 !>(loop$ for pair in (regression-suite)
                always (equal (sim *system* (car pair)) (cdr pair)))
  })

  <p>which simulates the @('*system*') on every input in the regression suite
  and compares the result to the known correct answer.</p>

  <p>The formal translation of this term is</p>

  @({
   (always$ '(lambda (loop$-ivar)
               (equal (sim '(#x488b55f0
                             #x31ff
                             #xff142570081050
                             #xf84995b0000
                             #xf645f801
                             #xf8573100000
                             #x807df019
                             ...)
                           (car loop$-ivar))
                      (cdr loop$-ivar)))
            (regression-suite))
  })

  <p>Note that the constant @('*system*') has been rendered as its quoted value
  and that it is inside of the @('lambda') object.  If @('*system*') is a very
  large constant, that @('lambda') object may be excessively large.</p>

  <p>But we can avoid that by writing this instead.</p>

  @({
  ACL2 !>(let ((sys *system*))
           (loop$ for pair in (regression-suite)
                  always (equal (sim sys (car pair)) (cdr pair))))
  })

  <p>which essentially translates to</p>

  @({
  (let ((sys '(#x488b55f0
               #x31ff
               #xff142570081050
               #xf84995b0000
               #xf645f801
               #xf8573100000
               #x807df019
               dots)))
    (always$+ '(lambda (loop$-gvars loop$-ivars)
                 (equal (sim (car loop$-gvars)
                             (car (car loop$-ivars)))
                        (cdr (car loop$-ivars))))
              (list sys)
              (loop$-as (list (regression-suite)))))
  })

  <p>Note that the @('lambda') object no longer contains the large constant.
  It now refers to a &ldquo;global&rdquo; variable whose value is that of
  @('*system*').  The @('lambda') object is quite small.</p>

  <p>For what it is worth, the largest single object in the ACL2 image (as of
  Version  8.6) is the value of @('(w state)'), the logical world.  Upon
  starting the system @('(w state)') contains 128,784 elements, but contains
  multiple pointers to shared substructures (e.g., to tails of itself).  The
  total number of conses is on the order of @('(expt 10 655)') when counted
  naively, but the total number of distinct conses is 1,875,653.  So if you
  build a @('lambda') object containing the value of @('(w state)') it will be
  &ldquo;excessively large.&rdquo;</p>")

(defxdoc explain-near-miss
  :parents (debugging)
  :short "show why a rule's pattern and the :target do not match"
  :long "<p>When a near miss break occurs (see @(tsee monitor)) the user
  sees a message like this:</p>

  @({
  (1 Breaking (:REWRITE LEMMA) on (F (G A B) A '(A B C D ...)):

  The pattern in this rule failed to match the target.  However, this
  is considered a NEAR MISS under the break criteria,
  (:CONDITION 'T :ABSTRACTION ...), specified when this rule was
  monitored.  The following criterion is satisfied.

  * The :ABSTRACTION pattern provided in your monitor, ...,
  matches :TARGET.
  })

  <p>It can be difficult to determine why the pattern of the rule, e.g., the
  @(':lhs') of a @(':rewrite') rule, fails to match the @(':target') term,
  especially when large terms, large quoted constants, and @('lambda')
  expressions are involved.</p>

  <p>Included among the @(':')@(tsee brr-commands) is the @(':explain-near-miss')
  command which is intended to help explain.  This command can only operate in
  a near miss break.  If called in another context an error may occur.</p>

  <p>But in a near miss break, the situation is as follows.  The prover has
  tried to apply a rule that has been monitored with a break criterion meaning
  ``cause an interactive break when the target term (the term to currently
  being rewritten) satisfies this criterion but the triggering pattern of the
  rule fails to match the target term.''  When inside the resulting break, the
  target term is given by the @(tsee brr) command @(':target').  The
  ``triggering pattern'' of the rule in question depends on how the rule was
  stored (see @(tsee rule-classes)).  The triggering pattern of a @(':')@(tsee
  rewrite) rule &mdash; the most common class of rule &mdash; is the left-hand
  side of the concluding equality and can be obtained from within the break by
  typing the @(tsee brr) command @(':lhs').  The triggering pattern for a
  @(':')@(tsee rewrite-quoted-constant) rule is its right-hand side, but as
  explained in @(tsee rewrite-quoted-constant), the @('brr') command @(':lhs')
  will display it.  The triggering pattern for a @(':')@(tsee linear) rule is
  displayed by the @(':')@('max-term') @('brr') command.  The question the user
  will typically ask in this situation is ``why doesn't the triggering pattern
  match the target?''</p>

  <p>To understand the answer you have to understand how the ACL2 matching
  algorithm works.  The matching algorithm is given two terms, @('t1') and
  @('t2'), and attempts to find a substitution @('s') on the variables in
  @('t1') such that when @('t1') is instantiated with @('s') the result is
  @('t2'), i.e., @('t1/s') = @('t2').  Note that only the variables in the
  pattern, @('t1'), can be instantiated by @('s'').  In the case of a near miss
  break, no such substitution was found.</p>

  <p>The @(':explain-near-miss') command reruns the matching algorithm on the
  triggering pattern and the target, expecting failure and collecting
  information about where the failure occurred.  The output is intended to be
  self-explanatory.</p>

  <p>The message displays the pattern in question and the target term, but it
  also displays a version of the pattern in which the first unmatchable subterm
  is replaced by the expression @('<pat>').  That @('<pat>') is displayed
  in lowercase whereas the rest of the pattern and target are in uppercase.
  It marks where the matching broke down.</p>

  <p>The message goes on to show the mismatched subterms from the pattern and
  the target, the substitution that was computed to match everything up to
  @('<pat>') and what the @('<pat>') subterm of the pattern is when
  instantiated with that substitution.</p>

  <p>So, for example, suppose the rule's @(':lhs') and the current @(':target')
  are as shown below.  Then here is what @(':explain-near-miss') would
  print.</p>

  @({
  The ACL2 match algorithm attempted to match :LHS with :TARGET by finding
  a substitution, s, such that :LHS/s = :TARGET.  That attempt failed
  when trying to match the subterm of :LHS marked <pat> in :LHS' below.

  :LHS:      (F X (G X Y) (H X))
  :LHS':     (F X (G <pat> Y) (H X))
  :TARGET:   (F A (G B A) (H A))

  Below we show the substitution, s, computed prior to the failure; the
  subterm of :LHS we're calling <pat>; the instantiated subterm, <pat>/s;
  and the corresponding subterm, <tar>, of :TARGET.

  s:       ((X A))
  <pat>:   X
  <pat>/s: A
  <tar>:   B

  For the rewriter to get past this failure the match algorithm must
  be able to extend substitution s to s' so that <pat>/s' is equal to
  <tar> and our match algorithm could not find such an extension.
  })

  <p>Note that the substitution @('s') binds @('X') to @('A') to match the
  first argument of the @('F')-expression in the @(':LHS') to the corresponding
  argument in the @(':TARGET').  Then it tries to match @('(G X Y)') with @('(G
  B A)').  It fails on the first argument of that subterm, where @('<pat>') is
  shown in @(':LHS''), because @('X') has been bound to @('A') and @('A') and
  @('B') are different.  (Remember: only the variables of the pattern can be
  bound by the substitution.)</p>

  <p>When @('<pat>') and its corresponding subterm @('<tar>') are ``large'' but
  unequal quoted constants or @('lambda') expressions, @(':explain-near-miss')
  will call @(tsee compare-objects) on those objects.  It can be hard to spot
  how two large constants differ and @('compare-objects') points out the
  differences between two @('cons') trees.  @(':Explain-near-miss') considers
  an object ``large'' if the number of conses in it is 30 or greater.</p>

  <p>The command @(':explain-near-miss+') is like @(':explain-near-miss')
  except it never eviscerates any term and runs @('compare-objects') whenever
  the failure is on two distinct quoted objects or @('lambda') expressions
  regardless of their sizes.</p>

  <p>But note that @('compare-objects') is not run by either version of
  @('explain-near-miss') when the failure is of the most common kinds:</p>

  <ul>

  <li>(a) a variable in the pattern has already been bound in the
  substitution (i.e., bound earlier in the matching process) to a term that is
  not identical to the corresponding term in the target, or</li>

  <li>(b) a term in the pattern has a different function symbol than the
  corresponding term the target.</li>

  </ul>

  <p>So do not expect the @('compare-objects') output to appear often!</p>")

(defxdoc explode-atom
  :parents (characters acl2-built-ins)
  :short "Convert any @(see atom) into a @(see character-listp) that contains
 its printed representation, rendering numbers in your choice of print base."
  :long "<p>@(call explode-atom) prints the atom @('x') as a list of
 characters, using some @(see print-base-p) to decide what base to print
 numbers in.</p>

 <p>Examples:</p>

 @({
 (explode-atom 15 10) --> (#\1 #\5)              ; 15 in decimal
 (explode-atom 15 16) --> (#\F)                  ; 15 in hex
 (explode-atom "foo" 10) --> (#\f #\o #\o)
 (explode-atom 'acl2::foo 10) --> (#\F #\O #\O)  ; note: no package
 })

 <p>See also @(see explode-nonnegative-integer), @(see str::numbers), and @(see
 printing-to-strings).</p>

 @(def explode-atom)")

(defxdoc explode-nonnegative-integer
  :parents (characters numbers acl2-built-ins)
  :short "The list of @(see characters) in the radix-r form of a number"
  :long "@({
  Examples:
  ACL2 !>(explode-nonnegative-integer 925 10 nil)
  (#9 #2 #5)
  ACL2 !>(explode-nonnegative-integer 325 16 nil)
  (#3 #9 #D)
 })

 <p>For a non-negative integer @('n'), @('(explode-nonnegative-integer n r
 nil)') is the list of @(see characters) in the radix-@('r') (base-@('r'))
 representation of @('n').</p>

 <p>The @(see 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).</p>

 <p>See also @(see explode-atom), @(see str::numbers), and @(see
 printing-to-strings).</p>

 @(def explode-nonnegative-integer)")

(defxdoc expt
  :parents (numbers acl2-built-ins)
  :short "Exponential function"
  :long "<p>@('(Expt r i)') is the result of raising the number @('r') to the
 integer power @('i').</p>

 <p>The @(see 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 @(see guard) aren't met,
 @('(expt r i)') first coerces @('r') to a number and @('i') to an integer.</p>

 <p>@('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.</p>

 @(def expt)")

(defxdoc extend-pathname
  :parents (io acl2-built-ins)
  :short "Extend a relative pathname to an absolute pathname"
  :long "<p>@('Extend-pathname') is a @(':')@(tsee program) mode function that
 takes a directory name as specified below and a filename (a string), and
 returns a corresponding pathname for the given file that is relative to the
 specified directory.  If the filename is already an absolute pathname then the
 return value is that filename, unchanged.</p>

 @({
 General Form:

 (extend-pathname dir filename state)
 })

 <p>where @('dir') is either a string, representing an absolute pathname for a
 directory, or a keyword, representing a project directory (see @(see
 project-dir-alist)); filename is a string representing a relative or absolute
 pathname; and @('state') is the ACL2 @(see state).</p>

 <p>The following examples illustrate the behavior of @('extend-pathname').</p>

 @({
 Examples (comments added)

 ACL2 !>(extend-pathname "~/temp" "foo.lisp" state)
 ; where the user is "bubba" here and in the remaining examples
 "/home/bubba/temp/foo.lisp"
 ACL2 !>(extend-pathname "~/temp/" "foo.lisp" state)
 ; the final / is optional for the directory name
 "/home/bubba/temp/foo.lisp"
 ACL2 !>(extend-pathname "~/temp/" "no-such-file" state)
 ; name of non-existent file is still extended
 "/home/bubba/temp/no-such-file"
 ACL2 !>(extend-pathname "." "no-such-file" state)
 ; THIS IS NOT SUPPORTED, because the first argument is a relative pathname,
 ; not an absolute pathname; but in this case a reasonable answer happens to
 ; be provided.  See the next example for how to do this properly.
 ; Here we assume that the current working directory is "/home/joe"
 "/home/joe/no-such-file"
 ACL2 !>(extend-pathname (canonical-pathname "." t state) "no-such-file" state)
 ; As above, but the first argument is first turned into an absolute pathname,
 ; which makes the call a supported one.
 "/home/joe/no-such-file"
 ACL2 !>(extend-pathname (cbd) "no-such-file" state)
 ; assumes that the connected book directory (see :DOC cbd) is "/data/santa"
 "/data/santa/no-such-file"
 ACL2 !>(extend-pathname :system "no-such-file" state)
 ; assumes that system books directory is "/data/acl2/books"
 "/data/acl2/books/no-such-file"
 ACL2 !>(extend-pathname "/data/acl2" "~/temp/foo.lisp" state)
 ; directory is ignored when filename is already absolute
 "/home/bubba/temp/foo.lisp"
 ACL2 !>(extend-pathname :system "~/temp/foo.lisp" state)
 ; directory is ignored when filename is already absolute
 "/home/bubba/temp/foo.lisp"
 })

 <p>Note that when the indicated file exists, @('extend-pathname') resolves
 symbolic links by using @(tsee canonical-pathname).  If you don't want
 symbolic links to be resolved there are simpler alternatives; for example, see
 @(see oslib::catpath).</p>")

(defxdoc extend-pe-table
  :parents (history)
  :short "Replace @(see events) displayed by @(see history) commands"
  :long "@({
 Example Form:
 (extend-pe-table all-natp (all-p natp))

 General Form:
 (extend-pe-table event-name form)
 })

 <p>where @('event-name') is the name of an existing event and @('form') is to
 be displayed by @(see history) commands in place of the actual event that
 introduced @('event-name').</p>

 <p>We motivate and illustrate this utility with the following example.
 Suppose you develop a macro to define the notion that each element of a list
 satisfies a given predicate, as follows.</p>

 @({
 (defmacro all-p (pred)
   (declare (xargs :guard (symbolp pred)))
   (let ((name (intern$ (concatenate 'string "ALL-" (symbol-name pred))
                        (symbol-package-name pred))))
     `(defun ,name (lst)
        (if (atom lst)
            t
          (and (,pred lst)
               (,name (cdr lst)))))))
 })

 <p>So for example, after evaluating @('(all-p natp)'), you see the
 following.</p>

 @({
 ACL2 !>:pe all-natp
  L         2:x(ALL-P NATP)
               
 >L             (DEFUN ALL-NATP (LST)
                       (IF (ATOM LST)
                           T
                           (AND (NATP LST) (ALL-NATP (CDR LST)))))
 ACL2 !>
 })

 <p>So far so good.  But suppose that instead, you introduce this event within
 a call of @(tsee progn), as follows.</p>

 @({
 (progn (defun f1 (x) x)
        (defun f2 (x) x)
        (all-p natp))
 })

 <p>Then when we ask to see the event introducing @('all-natp'), we will not
 see any use of the macro @('all-p').</p>

 @({
 ACL2 !>:pe all-natp
            2:x(PROGN (DEFUN F1 # ...)
                      (DEFUN F2 # ...)
                      ...)
               
 >L             (DEFUN ALL-NATP (LST)
                       (IF (ATOM LST)
                           T
                           (AND (NATP LST) (ALL-NATP (CDR LST)))))
 ACL2 !>
 })

 <p>Perhaps we therefore prefer that @(see history) commands display the event
 for @('all-natp') as @('(all-p natp)'), rather than as the generated @(tsee
 defun) event.  Of course, in this simple example that might not be important;
 but it is easy to imagine examples where a small macro invocation generates a
 large, ugly primitive event that is best not viewed by any user!</p>

 <p>A solution is to associate the name @('all-natp') with the form that
 introduced this name, as follows.</p>

 @({
 (extend-pe-table all-natp (all-p natp))
 })

 <p>After evaluating this form, we see the desired call of @('all-natp').  In
 essence, @(':')@(tsee pe) and other @(see history) commands consider the
 defining event for @('all-natp') to be @('(all-p natp)') rather than the
 actual @('defun') form that introduced @('all-natp').</p>

 @({
 ACL2 !>:pe all-natp
            2  (PROGN (DEFUN F1 # ...)
                      (DEFUN F2 # ...)
                      ...)
               
 >L             (ALL-P NATP)
 ACL2 !>
 })

 <p>As mentioned above, other @(see history) commands are sensitive to the
 result of evaluating a call of @('extend-pe-table').  For example:</p>

 @({
 ACL2 !>:pcb all-natp
            2  (PROGN (DEFUN F1 # ...)
                      (DEFUN F2 # ...)
                      ...)
  L             (DEFUN F1 (X) ...)
  L             (DEFUN F2 (X) ...)
  L             (ALL-P NATP)
 ACL2 !>
 })

 <p>Note that @('extend-pe-table') actually associates the indicated form with
 the most recent event introducing the given event name.  Consider the
 following example (output elided as shown).</p>

 @({
 ACL2 !>(encapsulate
          ()
          (program)
          (all-p alistp))
 [[.. elided ..]]
  T
 ACL2 !>:pe all-alistp
            4:x(ENCAPSULATE NIL ...)
               
 >P             (DEFUN ALL-ALISTP (LST)
                       (IF (ATOM LST)
                           T
                           (AND (ALISTP LST)
                                (ALL-ALISTP (CDR LST)))))
 ACL2 !>(extend-pe-table all-alistp (all-p alistp))

 Summary
 Form:  ( TABLE PE-TABLE ...)
 Rules: NIL
 Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
  PE-TABLE
 ACL2 !>:pe all-alistp
            4  (ENCAPSULATE NIL ...)
               
 >P             (ALL-P ALISTP)
 ACL2 !>(verify-termination all-alistp)
 [[.. elided ..]]
  ALL-ALISTP
 ACL2 !>:pe all-alistp
  L         6:x(VERIFY-TERMINATION ALL-ALISTP)
               
 >L             (DEFUN ALL-ALISTP (LST)
                       (IF (ATOM LST)
                           T
                           (AND (ALISTP LST)
                                (ALL-ALISTP (CDR LST)))))

 Additional events for the logical name ALL-ALISTP:
            4  (ENCAPSULATE NIL ...)
               
 >PL            (ALL-P ALISTP)
 ACL2 !>(extend-pe-table all-alistp (:termination-verified (all-p alistp)))

 Summary
 Form:  ( TABLE PE-TABLE ...)
 Rules: NIL
 Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
  PE-TABLE
 ACL2 !>:pe all-alistp
  L         6  (VERIFY-TERMINATION ALL-ALISTP)
               
 >L             (:TERMINATION-VERIFIED (ALL-P ALISTP))

 Additional events for the logical name ALL-ALISTP:
            4  (ENCAPSULATE NIL ...)
               
 >PL            (ALL-P ALISTP)
 ACL2 !>
 })

 <p>Note that by using @(':')@(tsee pe!), in place of @(':')@(tsee pe), you can
 avoid using the information that was provided by @('extend-pe-table').</p>

 @({
 ACL2 !>:pe! all-alistp
  L         6  (VERIFY-TERMINATION ALL-ALISTP)
               
 >L             (DEFUN ALL-ALISTP (LST)
                       (IF (ATOM LST)
                           T
                           (AND (ALISTP LST)
                                (ALL-ALISTP (CDR LST)))))

 Additional events for the logical name ALL-ALISTP:
            4  (ENCAPSULATE NIL ...)
               
 >PL            (DEFUN ALL-ALISTP (LST)
                       (IF (ATOM LST)
                           T
                           (AND (ALISTP LST)
                                (ALL-ALISTP (CDR LST)))))
 ACL2 !>
 })

 <p>In the examples above we invoked @('extend-pe-table') explicitly.  It might
 have been better, however, to ``bake in'' such calls by way of the macro
 itself, as follows.</p>

 @({
 (defmacro all-p (&whole form pred)
   (declare (xargs :guard (symbolp pred)))
   (let ((name (intern$ (concatenate 'string "ALL-" (symbol-name pred))
                        (symbol-package-name pred))))
     `(progn (defun ,name (lst)
               (if (atom lst)
                   t
                 (and (,pred lst)
                      (,name (cdr lst)))))
             (extend-pe-table ,name ,form))))
 })

 <p>Then in a fresh session, after defining @('all-p') as shown immediately
 above, we can obtain the following (edited) log.</p>

 @({
 ACL2 !>(all-p natp)
 [[.. elided ..]]
 ACL2 !>:pe all-natp
            2:x(ALL-P NATP)
 ACL2 !>
 })

 <p>We close with two remarks.  First, note that the indicated event must have
 already been defined at the time @('extend-pe-table') is invoked.  Second
 &mdash; in case an advanced user wishes to extend directly the underlying
 table, @('pe-table') &mdash; we mention that this table associates each key,
 an event name, with an association list that maps so-called absolute event
 numbers with events to display.  So for example, we can remove all custom
 printing of events for the name @('all-natp') as follows.</p>

 @({
 (table pe-table 'all-natp nil)
 })

")

(defxdoc extend-world
  :parents (world)
  :short "Install an extension of a given ACL2 @(see world)"
  :long "<p>See @(see world) for relevant background on ACL2 property list
 worlds.  Here we discuss how to install an extension of a user-defined world,
 that is, a world other than the one named @(''current-acl2-world'), which is
 maintained by the ACL2 system.  Also see @(see retract-world) for a similar
 utility that instead installs an initial segment of a named world.</p>

 @({
 General Form:

 (extend-world name wrld)
 })

 <p>where @('name') is a symbol intended to name the given ACL2 property list
 world, @('world').  Consider the following example.</p>

 @({
 ACL2 !>(let* ((wrld0 nil)
               (wrld1 (putprop 'my-sym1 'my-key1 'my-val1-old wrld0))
               (wrld2 (putprop 'my-sym2 'my-key2 'my-val2 wrld1))
               (wrld3 (putprop 'my-sym1 'my-key1 'my-val1 wrld2)))
          (assign my-w (extend-world 'my-world wrld3)))
  ((MY-SYM1 MY-KEY1 . MY-VAL1)
   (MY-SYM2 MY-KEY2 . MY-VAL2)
   (MY-SYM1 MY-KEY1 . MY-VAL1-OLD))
 ACL2 !>(getprop 'my-sym1 'my-key1 nil 'my-world (@ my-w))
 MY-VAL1
 ACL2 !>
 })

 <p>The first top-level form sets the value of @(tsee state) global @('my-w')
 to the world obtained by extending the empty world three times, as shown.  The
 second top-level form returns the most recent @(''my-key1') property of the
 symbol @(''my-sym1').  This second computation is efficient, because
 @('extend-world') has <i>installed</i> the value of @('my-w') as the world
 that is current for the name @(''my-world').  See @(see world).</p>")

(defxdoc extended-metafunctions
  :parents (meta)
  :short "State and context sensitive metafunctions"
  :long "@({
  General Form of an Extended :Meta theorem:
  (implies (and (pseudo-termp x)              ; this hyp is optional
                (alistp a)                    ; this hyp is optional
                (ev (hyp-fn x mfc state) a)   ; this hyp is optional
                ; meta-extract hyps may also be included (see below)
                )
           (equiv (ev x a)
                  (ev (fn x mfc state) a)))
 })

 <p>where the restrictions are as described in the @(see documentation) for
 @(tsee meta) where @('state') is literally the symbol @('STATE'), and @('x'),
 @('a'), @('mfc'), and @('state') are distinct variable symbols.  A @(':meta')
 theorem of the above form installs @('fn') as a metatheoretic simplifier with
 hypothesis function @('hyp-fn'), exactly as for vanilla metafunctions.  The
 only difference is that when the metafunctions are applied, some contextual
 information is passed in via the @('mfc') argument and the ACL2 @(tsee state)
 is made available.</p>

 <p>See @(see meta) for a discussion of vanilla flavored metafunctions.  This
 documentation assumes you are familiar with the simpler situation, in
 particular, how to define a vanilla flavored metafunction, @('fn'), and its
 associated hypothesis metafunction, @('hyp-fn'), and how to state and prove
 metatheorems installing such functions.  Defining extended metafunctions
 requires that you also be familiar with many ACL2 implementation details.
 This documentation is sketchy on these details; see the ACL2 source code or
 email the @(see acl2-help) list if you need more help.</p>

 <p>To test your extended metafunctions outside of proof attempts, see @(see
 trust-mfc).</p>

 <p>Additional hypotheses are supported, called ``meta-extract hypotheses'',
 that allow metafunctions to depend on the validity of certain terms extracted
 from the context or the logical @(see world).  These hypotheses provide an
 even more advanced form of metatheorem so we explain them elsewhere; see @(see
 meta-extract).</p>

 <p>The metafunction context, @('mfc'), is a list containing many different
 data structures used by various internal ACL2 functions.  Generally, your
 extended metafunction will take @('mfc') as its second formal and pass it into
 the functions mentioned below.  However, advanced users who want other access
 to @('mfc') may wish to see the documentation for @(see mfc).  The ACL2
 @('state') is well-documented (see @(see state)).  Below we present
 expressions below that can be useful in defining extended metafunctions.  Some
 of these expressions involve keyword arguments, @(':forcep') and @(':ttree'),
 which are optional and in most cases are fine to omit, and which we explain
 after we present the useful expressions.</p>

 <p>@('(mfc-clause mfc)'): returns the current goal, in clausal form.  A clause
 is a list of ACL2 terms, implicitly denoting the disjunction of the listed
 terms.  The @(see clause) returned by @('mfc-clause') is the clausal form of
 the translation (see @(see trans)) of the goal or subgoal on which the
 rewriter is working.  When a metafunction calls @('mfc-clause'), the term,
 @('term-mf'), being rewritten by the metafunction has resulted from an attempt
 to rewrite some term, @('term-cl'), in this clause.  These could be the same
 term, but that need not be the case: for example, @('term-mf') could be a term
 to which the rewriter has backchained while trying to rewrite @('term-cl'), or
 @('term-mf') could arise from the right-hand side of a rewrite rule applied to
 @('term-cl').</p>

 <p>@('(mfc-ancestors mfc)'): returns an alist whose keys are the negations of
 the backchaining hypotheses being pursued.  In particular, @('(null
 (mfc-ancestors mfc))') will be true exactly when rewriting is on part of the
 current goal.  Exception: An element of this alist whose key is of the form
 @('(:binding-hyp hyp unify-subst)') indicates that @('hyp') has been
 encountered as a hypothesis of the form @('(equal var term)') or @('(equiv var
 (double-rewrite-term))'), in each case binding variable @('var') to the result
 of rewriting @('term') under @('unify-subst').</p>

 <p>@('(mfc-rdepth mfc)'): returns the remaining stack depth for calls of the
 rewriter (by default, @('*default-rewrite-stack-limit*') at the top level; see
 @(see rewrite-stack-limit)).  When this is 0, no further calls of the rewriter
 can be made without error.</p>

 <p>@('(mfc-type-alist mfc)'): returns the type-alist governing the occurrence
 of the term, @('x'), being rewritten by the metafunction.  A type-alist is an
 association list, each element of which is of the form @('(term ts . ttree)').
 Such an element means that the term @('term') has the @(see type-set) @('ts');
 see @(see type-alist).  The @('ttree') component is probably irrelevant here.
 All the terms in the type-alist are in translated form (see @(see trans)).
 The @('ts') are numbers denoting finite Boolean combinations of ACL2's
 primitive types (see @(see type-set)).  The type-alist includes not only
 information gleaned from the conditions governing the term being rewritten but
 also that gleaned from forward chaining from the (negations of the) other
 literals in the clause returned by @('mfc-clause').</p>

 <p>@('(mfc-unify-subst mfc)'): returns @('nil') except when evaluating a
 @(tsee syntaxp) or @(tsee bind-free) hypothesis, in which case, returns the
 unifying substitution present at the start of that evaluation.</p>

 <p>@('(mfc-world mfc)'): returns the ACL2 logical @(tsee world).</p>

 <p>@('(mfc-ts term mfc state :forcep forcep :ttreep ttreep)'): returns the
 @('type-set') of @('term') in the current context; see @(see type-set).</p>

 <p>@('(mfc-rw term obj equiv-info mfc state)'): returns the result of
 rewriting @('term') in the current context, @('mfc'), with objective @('obj')
 and the equivalence relation described by @('equiv-info').  @('Obj') should be
 @('t'), @('nil'), or @('?'), and describes your objective: try to show that
 @('term') is true, false, or anything.  @('Equiv-info') is either @('nil'),
 @('t'), a function symbol @('fn') naming a known equivalence relation, or a
 list of congruence rules.  @('Nil') means return a term that is @('equal') to
 @('term').  @('T') means return a term that is propositionally equivalent
 (i.e., in the @('iff') sense) to @('term'), while @('fn') means return a term
 @('fn')-equivalent to @('term').  The final case, which is intended only for
 advanced users, allows the specification of generated equivalence relations,
 as supplied to the @('geneqv') argument of @('rewrite').  Generally, if you
 wish to establish that @('term') is true in the current context, use the
 idiom</p>

 @({
  (equal (mfc-rw term t t mfc state) *t*)
 })

 <p>The constant @('*t*') is set to the internal form of the constant term
 @('t'), i.e., @(''t').</p>

 <p>@('(mfc-rw+ term alist obj equiv-info mfc state)'): if @('alist') is
 @('nil') then this is equivalent to @('(mfc-rw term obj equiv-info mfc
 state)').  However, the former takes an argument, @('alist'), that binds
 variables to terms, and returns the result of rewriting @('term') under that
 @('alist'), where this rewriting is as described for @('mfc-rw') above.  The
 function @('mfc-rw+') can be more efficient than @('mfc-rw'), because the
 terms in the binding alist have generally already been rewritten, and it can
 be inefficient to rewrite them again.  For example, consider a rewrite rule of
 the following form.</p>

 @({
  (implies (and ...
                (syntaxp (... (mfc-rw `(bar ,x) ...) ...))
                ...)
           (equal (... x ...) ...))
 })

 <p>Here, @('x') is bound in the conclusion to the result of rewriting some
 term, say, @('tm').  Then the above call of @('mfc-rw') will rewrite @('tm'),
 which is probably unnecessary.  So a preferable form of the rule above may be
 as follows, so that @('tm') is not further rewritten by @('mfc-rw+').</p>

 @({
  (implies (and ...
                (syntaxp (... (mfc-rw+ '(bar v) `((v . ,x)) ...) ...))
                ...)
           (equal (... x ...) ...))
 })

 <p>However, you may find that the additional rewriting done by @('mfc-rw') is
 useful in some cases.</p>

 <p>@('(mfc-ap term mfc state)'): returns @('t') or @('nil') according to
 whether linear arithmetic can determine that @('term') is false.  To the
 cognoscenti: returns the contradiction flag produced by linearizing @('term')
 and adding it to the @('linear-pot-lst').</p>

 <p>@('(mfc-relieve-hyp hyp alist rune target bkptr mfc state)'): returns
 @('t') or @('nil') according to whether the indicated hypothesis term,
 @('hyp'), can be relieved (proved) under the giving variable bindings,
 @('alist').  Note that this function returns @('nil') if @('hyp') has free
 variables (see @(see free-variables)).  Here, @('hyp') is the hypothesis of
 the indicated @(tsee rune) at (one-based) position @('bkptr'), and @('target')
 is an instantiated term to which @('rune') is being applied.  Note that no
 indication is returned for whether any assumptions have been generated by
 @(tsee force) or @(tsee case-split).  (If you need such a feature, feel free
 to request it of the ACL2 implementors.)</p>

 <p>We explain the @(':forcep') and @(':ttreep') keyword arguments provided in
 some expressions, as promised above.  Their defaults are @(':same') and
 @('nil'), respectively.  A value of @(':same') for @(':forcep') means that
 forcing will be allowed if and only if it is allowed in the current rewriting
 environment; see @(see force).  A value of @('t') or @('nil') for @(':forcep')
 overrides this default and allows or disallows forcing, respectively.  By
 default these functions return a single value, @('val'), but if @(':ttreep')
 is @('t') then they return @('(mv val ttree)'), where @('ttree') is the
 tag-tree (see @(see ttree)) returned by the indicated operation, with an input
 tag-tree of @('nil')).</p>

 <p>During the execution of a metafunction by the theorem prover, the
 expressions above compute the results specified.  Typically, you should
 imagine that there are no axioms about the @('mfc-') function symbols: treat
 them as uninterpreted function symbols.  There is an advanced feature,
 meta-extract hypotheses, that can avoid this logical weakness in some cases
 when proving @(':')@(tsee meta) rules; see @(see meta-extract).  But we assume
 for the rest of the present @(see documentation) topic that you do not use
 meta-extract hypotheses.  Thus, in the proof of the correctness of a
 metafunction, no information is available about the results of these
 functions: you should <i>use these functions for heuristic purposes
 only</i>.</p>

 <p>For example, your metafunction may use these functions to decide whether to
 perform a given transformation, but the transformation must be sound
 regardless of the value that your metafunction returns.  We illustrate this
 below.  It is sometimes possible to use the hypothesis metafunction,
 @('hyp-fn'), to generate a sufficient hypothesis to justify the
 transformation.  The generated hypothesis might have already been ``proved''
 internally by your use of @('mfc-ts') or @('mfc-rw'), but the system will have
 to prove it ``officially'' by relieving it.  We illustrate this below
 also.</p>

 <p>We conclude with a script that defines, verifies, and uses several extended
 metafunctions.  This script is based on one provided by Robert Krug, who was
 instrumental in the development of this style of metafunction and whose help
 we gratefully acknowledge.</p>

 @({
  ; Here is an example.  I will define (foo i j) simply to be (+ i j).
  ; But I will keep its definition disabled so the theorem prover
  ; doesn't know that.  Then I will define an extended metafunction
  ; that reduces (foo i (- i)) to 0 provided i has integer type and the
  ; expression (< 10 i) occurs as a hypothesis in the clause.

  ; Note that (foo i (- i)) is 0 in any case.

  (defun foo (i j) (+ i j))

  (defevaluator eva eva-lst ((foo i j)
                             (unary-- i)

  ; I won't need these two cases until the last example below, but I
  ; include them now.

                             (if x y z)
                             (integerp x)))

  (set-state-ok t)

  (defun metafn (x mfc state)
    (cond
     ((and (consp x)
           (equal (car x) 'foo)
           (equal (caddr x) (list 'unary-- (cadr x))))

  ; So x is of the form (foo i (- i)).  Now I want to check some other
  ; conditions.

      (cond ((and (ts-subsetp (mfc-ts (cadr x) mfc state)
                              *ts-integer*)
                  (member-equal `(NOT (< '10 ,(cadr x)))
                                (mfc-clause mfc)))
             (quote (quote 0)))
            (t x)))
     (t x)))

  (defthm metafn-correct
    (equal (eva x a) (eva (metafn x mfc state) a))
    :rule-classes ((:meta :trigger-fns (foo))))

  (in-theory (disable foo))

  ; The following will fail because the metafunction won't fire.
  ; We don't know enough about i.

  (thm (equal (foo i (- i)) 0))

  ; Same here.

  (thm (implies (and (integerp i) (< 0 i)) (equal (foo i (- i)) 0)))

  ; But this will work.

  (thm (implies (and (integerp i) (< 10 i))
                (equal (foo i (- i)) 0)))

  ; This won't, because the metafunction looks for (< 10 i) literally,
  ; not just something that implies it.

  (thm (implies (and (integerp i) (< 11 i))
                (equal (foo i (- i)) 0)))

  ; Now I will undo the defun of metafn and repeat the exercise, but
  ; this time check the weaker condition that (< 10 i) is provable
  ; (by rewriting it) rather than explicitly present.

  (ubt 'metafn)

  (defun metafn (x mfc state)
    (cond
     ((and (consp x)
           (equal (car x) 'foo)
           (equal (caddr x) (list 'unary-- (cadr x))))
      (cond ((and (ts-subsetp (mfc-ts (cadr x) mfc state)
                              *ts-integer*)
                  (equal (mfc-rw `(< '10 ,(cadr x)) t t mfc state)
                         *t*))

  ; The mfc-rw above rewrites (< 10 i) with objective t and iffp t.  The
  ; objective means the theorem prover will try to establish it.  The
  ; iffp means the theorem prover can rewrite maintaining propositional
  ; equivalence instead of strict equality.

             (quote (quote 0)))
            (t x)))
     (t x)))

  (defthm metafn-correct
    (equal (eva x a) (eva (metafn x mfc state) a))
    :rule-classes ((:meta :trigger-fns (foo))))

  (in-theory (disable foo))

  ; Now it will prove both:

  (thm (implies (and (integerp i) (< 10 i))
                (equal (foo i (- i)) 0)))

  (thm (implies (and (integerp i) (< 11 i))
                (equal (foo i (- i)) 0)))

  ; Now I undo the defun of metafn and change the problem entirely.
  ; This time I will rewrite (integerp (foo i j)) to t.  Note that
  ; this is true if i and j are integers.  I can check this
  ; internally, but have to generate a hyp-fn to make it official.

  (ubt 'metafn)

  (defun metafn (x mfc state)
    (cond
     ((and (consp x)
           (equal (car x) 'integerp)
           (consp (cadr x))
           (equal (car (cadr x)) 'foo))

  ; So x is (integerp (foo i j)).  Now check that i and j are
  ; ``probably'' integers.

      (cond ((and (ts-subsetp (mfc-ts (cadr (cadr x)) mfc state)
                              *ts-integer*)
                  (ts-subsetp (mfc-ts (caddr (cadr x)) mfc state)
                              *ts-integer*))
             *t*)
            (t x)))
     (t x)))

  ; To justify this transformation, I generate the appropriate hyps.

  (defun hyp-fn (x mfc state)

    (declare (ignore mfc state))

  ; The hyp-fn is run only if the metafn produces an answer different
  ; from its input.  Thus, we know at execution time that x is of the
  ; form (integerp (foo i j)) and we know that metafn rewrote
  ; (integerp i) and (integerp j) both to t.  So we just produce their
  ; conjunction.  Note that we must produce a translated term; we
  ; cannot use the macro AND and must quote constants!  Sometimes you
  ; must do tests in the hyp-fn to figure out which case the metafn
  ; produced, but not in this example.

             `(if (integerp ,(cadr (cadr x)))
                  (integerp ,(caddr (cadr x)))
                  'nil))

  (defthm metafn-correct
    (implies (eva (hyp-fn x mfc state) a)
             (equal (eva x a) (eva (metafn x mfc state) a)))
    :rule-classes ((:meta :trigger-fns (integerp))))

  (in-theory (disable foo))

  ; This will not be proved.

  (thm (implies (and (rationalp x) (integerp i)) (integerp (foo i j))))

  ; But this will be.

  (thm (implies (and (rationalp x)
                     (integerp i)
                     (integerp j))
                (integerp (foo i j))))
 })")

(defxdoc extra-info
  :parents (guard)
  :short "Sources of measure, guard, or constraint proof obligations"
  :long "<p>@('(Extra-info x y)') always returns @('t') by definition.  See
 @(see guard-debug) and see @(see measure-debug) for a discussion of this
 function, which is useful for debugging failures from attempts to prove
 measure conjectures or to verify @(see guard)s.  See @(see
 set-constraint-tracking) to see how @('extra-info') can help in debugging
 failures to prove constraint obligations generated by
 @(':functional-instance') @(see hints) (see @(see lemma-instance)).</p>")

(defxdoc |Evaluating App on Sample Input|
  :parents (|Pages Written Especially for the Tours|)
  :short "Evaluating App on Sample Input"
  :long "<p><see topic='@(url |The Associativity of App|)'><img
 src='res/tours/walking.gif'></img></see></p>

 <p><img src='res/tours/green-line.gif'></img></p>

 <p>Click <see topic='@(url symbols)'>here</see> <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> for an explanation of conversion of
 symbols to upper case.</p>

 <code>
 ACL2 !&gt;<b>(app nil '(x y z))</b>
 (X Y Z)

 ACL2 !&gt;<b>(app '(1 2 3) '(4 5 6 7))</b>
 (1 2 3 4 5 6 7)

 ACL2 !&gt;<b>(app '(a b c d e f g) '(x y z))</b>
 (A B C D E F G X Y Z)

 ACL2 !&gt;<b>(app (app '(1 2) '(3 4)) '(5 6))</b>
 (1 2 3 4 5 6)

 ACL2 !&gt;<b>(app '(1 2) (app '(3 4) '(5 6)))</b>
 (1 2 3 4 5 6)

 ACL2!&gt;<b>(let ((a '(1 2))</b>
             <b>(b '(3 4))</b>
             <b>(c '(5 6)))</b>
         <b>(equal (app (app a b) c)</b>
                <b>(app a (app b c))))</b>
 T
 </code>

 <p><img src='res/tours/green-line.gif'></img></p>

 <p>As we can see from these examples, ACL2 functions can be executed more or
 less as Common Lisp.</p>

 <p>The last three examples suggest an interesting property of @('app').</p>

 <p><see topic='@(url |The Associativity of App|)'><img
 src='res/tours/walking.gif'></img></see></p>")

(defxdoc f-boundp-global
  :parents (programming-with-state acl2-built-ins)
  :short "Check whether a global variable in @(tsee state) has a value"
  :long "@({
  Examples:
  (f-boundp-global 'y state)

  General Form:
  (f-boundp-global s state)
 })

 <p>where @('s') evaluates to a symbol.  Note that this executes more
 efficiently when @('s') is a constant of the form @(''sym').</p>

 <p>This value returned is @('t') or @('nil') according to whether a value is
 assigned to the given symbol in the ACL2 @(see state).  Also see related
 utilities @(tsee f-get-global), @(tsee f-put-global), and @(tsee
 makunbound-global).</p>")

(defxdoc f-get-global
  :parents (programming-with-state acl2-built-ins)
  :short "Get the value of a global variable in @(tsee state)"
  :long "@({
  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)
 })

 <p>where @('symbol') is any symbol to which you have @(tsee assign)ed a global
 value.</p>

 <p>The macro @(tsee @) is closely related to @('f-get-global'): @('(@ var)')
 macroexpands to @('(f-get-global 'var state)').</p>

 <p>The macro @(tsee f-put-global) makes it convenient to set the value of a
 symbol.  The @(':')@(tsee ubt) operation has no effect on the
 @('global-table') of @(tsee 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.</p>")

(defxdoc f-put-global
  :parents (programming-with-state acl2-built-ins)
  :short "Assign to a global variable in @(tsee state)"
  :long "@({
  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)
 })

 <p>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 @(tsee
 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.)</p>

 <p>The macro @(tsee assign) is closely related to @('f-put-global'):
 @('(assign var val)') macroexpands to @('(f-put-global 'var val state)').</p>

 <p>The macros @(tsee @) and @(tsee f-get-global) give convenient access to the
 value of such globals.  The @(':')@(tsee ubt) operation has no effect on the
 @('global-table') of @(tsee 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.</p>")

(defxdoc failed-forcing
  :parents (force debugging)
  :short "How to deal with a proof @(see failure) in a forcing round"
  :long "<p>See @(see forcing-round) for a background discussion of the notion
 of forcing rounds.  When a proof fails during a forcing round it means that
 the ``gist'' of the proof succeeded but some ``technical detail'' failed.  The
 first question you must ask yourself is whether the @(see force)d goals are
 indeed theorems.  We discuss the possibilities below.</p>

 <p>If you believe the @(see force)d goals are theorems, you should follow the
 usual methodology for ``fixing'' failed ACL2 proofs, e.g., the identification
 of key lemmas and their timely and proper use as rules.  See @(see failure),
 see @(see gag-mode), and see @(see proof-tree).</p>

 <p>The rules designed for the goals of forcing rounds are often just what is
 needed to prove the @(see force)d hypothesis at the time it is @(see force)d.
 Thus, you may find that when the system has been ``taught'' how to prove the
 goals of the forcing round no forcing round is needed.  This is intended as a
 feature to help structure the discovery of the necessary rules.</p>

 <p>If a hint must be provided to prove a goal in a forcing round, the
 appropriate ``goal specifier'' (the string used to identify the goal to which
 the hint is to be applied) is just the text printed on the line above the
 formula, e.g., @('"[1]Subgoal *1/3''"').  See @(see goal-spec).</p>

 <p>If you solve a forcing problem by giving explicit @(see hints) for the
 goals of forcing rounds, you might consider whether you could avoid forcing
 the assumption in the first place by giving those @(see hints) in the
 appropriate places of the main proof.  This is one reason that we print out
 the origins of each @(see force)d assumption.  An argument against this style,
 however, is that an assumption might be @(see force)d in hundreds of places in
 the main goal and proved only once in the forcing round, so that by delaying
 the proof you actually save time.</p>

 <p>We now turn to the possibility that some goal in the forcing round is not a
 theorem.</p>

 <p>There are two possibilities to consider.  The first is that the original
 theorem has insufficient hypotheses to ensure that all the @(see force)d
 hypotheses are in fact always true.  The ``fix'' in this case is to amend the
 original conjecture so that it has adequate hypotheses.</p>

 <p>A more difficult situation can arise and that is when the conjecture has
 sufficient hypotheses but they are not present in the forcing round goal.
 This can be caused by what we call ``premature'' forcing.</p>

 <p>Because ACL2 rewrites from the inside out, it is possible that it will
 @(see force) hypotheses while the context is insufficient to establish them.
 Consider trying to prove @('(p x (foo x))').  We first rewrite the formula in
 an empty context, i.e., assuming nothing.  Thus, we rewrite @('(foo x)') in an
 empty context.  If rewriting @('(foo x)') @(see force)s anything, that @(see
 force)d assumption will have to be proved in an empty context.  This will
 likely be impossible.</p>

 <p>On the other hand, suppose we did not attack @('(foo x)') until after we
 had expanded @('p').  We might find that the value of its second argument,
 @('(foo x)'), is relevant only in some cases and in those cases we might be
 able to establish the hypotheses @(see force)d by @('(foo x)').  Our premature
 forcing is thus seen to be a consequence of our ``over eager'' rewriting.</p>

 <p>Here, just for concreteness, is an example you can try.  In this example,
 @('(foo x)') rewrites to @('x') but has a @(see force)d hypothesis of
 @('(rationalp x)').  @('P') does a case split on that very hypothesis and uses
 its second argument only when @('x') is known to be rational.  Thus, the
 hypothesis for the @('(foo x)') rewrite is satisfied.  On the false branch of
 its case split, @('p') simplifies to @('(p1 x)') which can be proved under the
 assumption that @('x') is not rational.</p>

 @({
  (defun p1 (x) (not (rationalp x)))
  (defun p (x y)(if (rationalp x) (equal x y) (p1 x)))
  (defun foo (x) x)
  (defthm foo-rewrite (implies (force (rationalp x)) (equal (foo x) x)))
  (in-theory (disable foo))
 })

 <p>The attempt then to do @('(thm (p x (foo x)))') @(see force)s the
 unprovable goal @('(rationalp x)').</p>

 <p>Since all ``formulas'' are presented to the theorem prover as single terms
 with no hypotheses (e.g., since @(tsee implies) is a function), this problem
 would occur routinely were it not for the fact that the theorem prover expands
 certain ``simple'' definitions immediately without doing anything that can
 cause a hypothesis to be @(see force)d.  See @(see simple).  This does not
 solve the problem, since it is possible to hide the propositional structure
 arbitrarily deeply.  For example, one could define @('p'), above, recursively
 so that the test that @('x') is rational and the subsequent first ``real'' use
 of @('y') occurred arbitrarily deeply.</p>

 <p>Therefore, the problem remains: what do you do if an impossible goal is
 @(see force)d and yet you know that the original conjecture was adequately
 protected by hypotheses?</p>

 <p>One alternative is to disable forcing entirely.  See @(see
 disable-forcing).  Another is to @(see disable) the rule that caused the @(see
 force).</p>

 <p>A third alternative is to prove that the negation of the main goal implies
 the @(see force)d hypothesis.  For example,</p>

 @({
  (defthm not-p-implies-rationalp
    (implies (not (p x (foo x))) (rationalp x))
    :rule-classes nil)
 })

 <p>Observe that we make no rules from this formula.  Instead, we merely
 @(':use') it in the subgoal where we must establish @('(rationalp x)').</p>

 @({
  (thm (p x (foo x))
       :hints (("Goal" :use not-p-implies-rationalp)))
 })

 <p>When we said, above, that @('(p x (foo x))') is first rewritten in an empty
 context we were misrepresenting the situation slightly.  When we rewrite a
 literal we know what literal we are rewriting and we implicitly assume it
 false.  This assumption is ``dangerous'' in that it can lead us to simplify
 our goal to @('nil') and give up &mdash; we have even seen people make the
 mistake of assuming the negation of what they wished to prove and then via a
 very complicated series of transformations convince themselves that the
 formula is false.  Because of this ``tail biting'' we make very weak use of
 the negation of our goal.  But the use we make of it is sufficient to
 establish the @(see force)d hypothesis above.</p>

 <p>A fourth alternative is to weaken your desired theorem so as to make
 explicit the required hypotheses, e.g., to prove</p>

 @({
  (defthm rationalp-implies-main
    (implies (rationalp x) (p x (foo x)))
    :rule-classes nil)
 })

 <p>This of course is unsatisfying because it is not what you originally
 intended.  But all is not lost.  You can now prove your main theorem from this
 one, letting the @(tsee implies) here provide the necessary case split.</p>

 @({
  (thm (p x (foo x))
       :hints (("Goal" :use rationalp-implies-main)))
 })")

(defxdoc failure
  :parents (debugging)
  :short "How to deal with a failure to admit an event"
  :long "<p>There are many reasons why an event can fail to be admitted.
 Generally, an error message will explain the failure, sometimes pointing to
 documentation that is specific to the relevant issue.  There are tools that
 can sometimes help: for example, to debug failures of @(tsee encapsulate) or
 @(tsee progn) events, as well as @(tsee certify-book) failures, see @(see
 redo-flat).</p>

 <p>However, proof failures are typically not as trivial to debug as, for
 example, syntactic errors (such as spelling errors in the name of a function).
 Fortunately, ACL2 offers a variety of techniques for dealing with proof
 failures, and some are discussed below.  Also see relevant subtopics of the
 topic, @(see debugging).  Some frequently-used tools for proof debugging that
 are discussed in those subtopics include @(see accumulated-persistence), @(see
 break-rewrite), @(see with-brr-data), @(see cgen), and @(see proof-builder).
 Also see @(see nil-goal) for ideas about how to proceed when the prover
 generates a goal of @('NIL').</p>

 <p>We turn now to the problem of dealing with proof failures.</p>

 <p>When ACL2 gives up it does not mean that the submitted conjecture is
 invalid, even if the last formula ACL2 printed in its proof attempt is
 manifestly false.  Since ACL2 sometimes @(see generalize)s the goal being
 proved, it is possible it adopted an invalid subgoal as a legitimate (but
 doomed) strategy for proving a valid goal.  Nevertheless, conjectures
 submitted to ACL2 are often invalid and the proof attempt often leads the
 careful reader to the realization that a hypothesis has been omitted or that
 some special case has been forgotten.  It is good practice to ask yourself,
 when you see a proof attempt fail, whether the conjecture submitted is
 actually a theorem.</p>

 <p>If you think the conjecture is a theorem, then you must figure out from
 ACL2's output what you know that ACL2 doesn't about the functions in the
 conjecture and how to impart that knowledge to ACL2 in the form of rules.  The
 ``key checkpoint'' information printed at the end of the @(see summary)
 provides a fine place to start.  See @(see the-method) for a general
 discussion of how to prove theorems with ACL2, and see @(see
 introduction-to-the-theorem-prover) for a more detailed tutorial.  Also see
 @(see set-gag-mode) for discussion of key checkpoints and an abbreviated
 output mode that focuses attention on them.  You may find it most useful to
 start by focusing on key checkpoints that are not under a proof by induction,
 if any, both because these are more likely to suggest useful lemmas and
 because they are more likely to be theorems; for example, generalization may
 have occurred before a proof by induction has begun.  If you need more
 information than is provided by the key checkpoints &mdash; although this
 should rarely be necessary &mdash; then you can look at the full proof,
 perhaps with the aid of certain utilities: see @(see pso), @(see
 set-gag-mode), and @(see proof-tree).  System hackers may want to consider
 using the utility, @(tsee checkpoint-list).</p>

 <p>Again, see @(see the-method) for a general discussion of how to prove
 theorems with ACL2, and see @(see introduction-to-the-theorem-prover) for a
 more detailed tutorial.  See also the book ``Computer-Aided Reasoning: An
 Approach'' (Kaufmann, Manolios, Moore), as well as the discussion of how to
 read Nqthm proofs and how to use Nqthm rules in ``A Computational Logic
 Handbook'' by Boyer and Moore (Academic Press, 1988).</p>

 <p>If the failure occurred during a forcing round, see @(see
 failed-forcing).</p>")

(defxdoc fancy-string-reader
  :parents (reader)
  :short "A friendly syntax for strings literals that have backslashes and
quotes."
  :long "<p>Examples:</p>
@({
     ACL2 !> #{"""Hello, World!"""}
     "Hello, World!"

     ACL2 !> #{"""<img src="hello.png"/>"""}
     "<img src=\"hello.png\"/>"

     ACL2 !> #{"""C:\ACL2\axioms.lisp"""}
     "C:\\ACL2\\axioms.lisp"
})

<p>String literals in ACL2 and Common Lisp source code files are usually
written as text strings within quote marks.  For instance, the 5-character
string whose contents are @('Hello') is normally written as @('"Hello"').</p>

<p>Usually this syntax is fine, but things can get tricky when you want to
write a string whose contents include @('"') marks.  For example, if you
wanted to write down a string whose contents were:</p>

@({
     <img src="hello.png"/>
})

<p>then you would need to escape the quote marks within it using backslash
characters, e.g., as follows:</p>

@({
     "<img src=\"hello.png\"/>"
})

<p>But using @('\') as a special character means we also need a special way to
write backslashes.  For instance, if we want to write a string literal whose
contents are:</p>

@({
      C:\ACL2\axioms.lisp
})

<p>Then we would need to write something a string literal such as:</p>

@({
      "C:\\ACL2\\axioms.lisp"
})

<p>In certain cases, such as when writing long @(see documentation) strings,
the extra escaping can be tedious and error-prone.</p>

<p>To simplify this, ACL2 provides an alternate @('#{"""..."""}') syntax
for string literals.  This syntax has no special characters, so nothing needs
to be escaped.  The end of the string is recognized by the unusual character
sequence @('"""}').</p>

<p>In the rare case that you need to have the sequence @('"""}') in your
string, you can instead use @('"""\}').  If you need to have the sequence
@('"""\}'), you can use @('"""\\}').  In general, when a substring
contains three doublequotes followed by 1 or more backslashes and a right
curlybrace, it just removes one of the backslashes.</p>")

(defxdoc fast-alist-clean
  :parents (fast-alists acl2-built-ins)
  :short "@('(fast-alist-clean alist)') can be used to eliminate
 "shadowed pairs" from a fast alist."
  :long "<p>This @(see documentation) topic assumes familiarity with fast
 alists; see @(see fast-alists).  See @(tsee fast-alist-clean!), @(tsee
 fast-alist-fork), and @(tsee fast-alist-fork!) for related utilities.</p>

 <p>Logically, @('(fast-alist-clean alist)') is defined as follows:</p>

 @(def fast-alist-clean)

 <p>The result is thus a corresponding fast alist, with the order reversed and
 with atoms and shadowed pairs removed, as per the definition above; see @(see
 fast-alist-fork) for details.  Moreover, if @('alist') is not a fast alist,
 then @('(fast-alist-clean alist)') is executed in raw Lisp by calling
 @('fast-alist-fork') as indicated above.</p>

 <p>However, if @('alist') is a fast alist, then a special definition under the
 hood provides a different handling of associated hash tables.  After running
 @('(fast-alist-clean alist)') to obtain a result, @('cleaned-alist'), the hash
 table that had been associated with @('alist') will now be associated with
 @('cleaned-alist') instead.  This saves the expense of creating a new hash
 table, but there is still the expense of copying the alist, as for @(tsee
 fast-alist-fork).  However, unlike @('fast-alist-fork'), there is no need to
 free the input alist.</p>

 <p>Note that the final @('cdr') is preserved, so that the name is preserved
 for use by @(tsee fast-alist-summary) (also see @(see hons-acons)).</p>")

(defxdoc fast-alist-clean!
  :parents (fast-alists acl2-built-ins)
  :short "@('(fast-alist-clean! alist)') is an alternative to @(tsee
fast-alist-clean) that produces a @(see normed) result."
  :long "<p>Logically this function is just @('fast-alist-clean'); we leave it
 enabled and would think it odd to ever prove a theorem about it.</p>

 <p>Under the hood, this is the same as @('fast-alist-clean') except that it
 uses something like @(tsee hons-acons!) instead of @(tsee hons-acons).  You
 generally <b>should not use</b> this function unless you really know what
 you're doing and understand the drawbacks discussed in @(tsee
 hons-acons!).</p>")

(defxdoc fast-alist-fork
  :parents (fast-alists acl2-built-ins)
  :short "@('(fast-alist-fork alist ans)') can be used to eliminate
"shadowed pairs" from an alist or to copy @(see fast-alists)."
  :long "<p>This @(see documentation) topic assumes familiarity with fast
 alists; see @(see fast-alists).  See @(tsee fast-alist-fork!), @(tsee
 fast-alist-clean), and @(tsee fast-alist-clean!) for related utilities.</p>

 <p>Logically, @('(fast-alist-fork alist ans)') is defined as follows:</p>

 @(def fast-alist-fork)

 <p>The alist argument need not be a fast alist.</p>

 <p>Typically ans is set to nil or some other atom.  In this case, shrinking
 produces a new, fast alist which is like alist except that (1) any
 "malformed," atomic entries have been removed, (2) all "shadowed pairs"
 have been removed, and (3) incidentally, the surviving elements have been
 reversed.  This can be useful as a way to clean up any unnecessary bindings in
 alist, or as a way to obtain a "deep copy" of a fast alist that can extended
 independently from the original while maintaining discipline.</p>

 <p>Note that fast-alist-fork is potentially expensive, for the following two
 reasons.</p>

 <ul>

 <li>The alist is copied, dropping any shadowed pairs.  This process will
 require a hash table lookup for each entry in the alist; and it will require
 creating a new alist, which uses additional memory.</li>

 <li>Unless ans is a fast alist that is stolen (see below), a new hash table
 is created, which uses additional memory.  This hash table is populated in
 time that is linear in the number of unique keys in the
 alist.</li>

 </ul>

 <p>When ans is not an atom, good discipline requires that it is a fast alist.
 In this case, @('fast-alist-fork') steals the hash table for ans and extends
 it with all of the bindings in alist that are not in ans.  From the
 perspective of @(tsee hons-assoc-equal), you can think of the resulting alist
 as being basically similar to @('(append ans alist)'), but in a different
 order.</p>

 <p>Note that when ans is not a fast alist (e.g., ans is an atom) then such
 stealing does not take place.</p>

 <p>A common idiom is to replace an alist by the result of shrinking it, in
 which case it is best to free the input alist, for example as follows.</p>

 @({
    (let ((alist (fast-alist-free-on-exit alist
                                          (fast-alist-fork alist nil))))
      ...)
 })

 <p>See @(see fast-alist-free-on-exit) and see @(see fast-alist-free).</p>

 ")

(defxdoc fast-alist-fork!
  :parents (fast-alists acl2-built-ins)
  :short "@('(fast-alist-fork! alist ans)') is an alternative to @(tsee
fast-alist-fork) that produces a @(see normed) result."
  :long "<p>Logically this function is just @('fast-alist-fork'); we leave it
 enabled and would think it odd to ever prove a theorem about it.</p>

 <p>Under the hood, this is the same as @('fast-alist-fork') except that it
 uses something like @(tsee hons-acons!) instead of @(tsee hons-acons).  You
 generally <b>should not use</b> this function unless you really know what
 you're doing and understand the drawbacks discussed in @(tsee
 hons-acons!).</p>")

(defxdoc fast-alist-free
  :parents (fast-alists acl2-built-ins)
  :short "@('(fast-alist-free alist)') throws away the hash table associated
with a fast alist."
  :long "<p>Logically, this function is the identity; we leave it enabled and
 would think it odd to ever prove a theorem about it.</p>

 <p>Under the hood, @('fast-alist-free') removes the hash table associated with
 this alist, if one exists.  This effectively converts the alist into an
 ordinary alist.</p>

 <p>Also see @(see fast-alist-free-on-exit).</p>

 <p>When the host Lisp is CCL or SBCL, the associated hash table may be freed
 up automatically by the garbage collector when the corresponding alist is no
 longer referenced.  (To trigger garbage collection manually, see @(see gc$).)
 But for Lisp implementations other than CCL and SBCL this is not the case so,
 to avoid memory leaks, you should use @('fast-alist-free') to free up
 associated hash tables that will no longer be used.  You may find @(tsee
 fast-alist-summary) useful in tracking down alists that were not properly
 freed.</p>

 <p>It is safe to call @('fast-alist-free') on any argument, including fast
 alists that have already been freed and objects which are not alists at
 all.</p>

 @(def fast-alist-free)")

(defxdoc fast-alist-free-on-exit
  :parents (fast-alists acl2-built-ins)
  :short "Free a fast alist after the completion of some form."
  :long "<p>Logically, @('(fast-alist-free-on-exit alist form)') is the
 identity and returns @('form').  Also see @(see fast-alist-free).</p>

 <p>Under the hood, this essentially expands to:</p>

 @({
   (prog1 form
          (fast-alist-free alist))
 })

 <p>In other words, @('alist') is not freed immediately, but instead remains a
 fast alist until the form completes.  This may be useful when you are writing
 code that uses a fast alist but has many return points.</p>

 <p>See also the macro @('fast-alists-free-on-exit') defined in the community
 book @('"books/centaur/misc/hons-extra.lisp"'), which can be used to free
 several alists.</p>

 <p>The community book @('"books/centaur/misc/hons-extra.lisp"') extends the
 @(see b*) macro with the @('free-on-exit') pattern binder.  That is, after
 executing @('(include-book "centaur/misc/hons-extra.lisp" :dir :system)'),
 the form</p>

 @({
   (b* (...
        ((free-on-exit a b c))
        ...)
     ...)
 })

 <p>causes @('a'), @('b'), and @('c') to be freed when the @('b*') completes,
 but they remain fast alists until then.</p>")

(defxdoc fast-alist-len
  :parents (fast-alists acl2-built-ins)
  :short "@('(fast-alist-len alist)') counts the number of unique keys in a
  fast alist."
  :long "<p>Logically this function counts how many elements would remain in
 the alist were we to shrink it with @(tsee fast-alist-fork).</p>

 <p>Good discipline requires that the alist is a fast alist.  Under the hood,
 when the alist is a fast alist we can simply call the underlying Common Lisp
 function @('hash-table-count') on the associated hash table, which is very
 fast and doesn't require us to actually shrink the alist.</p>

 @(def fast-alist-len)")

(defxdoc fast-alist-summary
  :parents (fast-alists acl2-built-ins)
  :short "@('(fast-alist-summary)') prints some basic statistics about any
current fast alists."
  :long "<p>Logically, @('fast-alist-summary') just returns nil; we leave it
 enabled and would think it odd to ever prove a theorem about it.</p>

 <p>Under the hood, this function gathers and prints some basic statistics
 about the current fast alists.  It may be useful for identifying fast alists
 that should have been freed with @(tsee fast-alist-free).</p>

 @(def fast-alist-summary)")

(defxdoc fast-alists
  :parents (alists programming hons-and-memoization)
  :short "Alists with hidden hash tables for faster execution"
  :long "<p>The implementation of fast alists is, in many ways, similar to that
 of ACL2 arrays.  Logically, @(tsee hons-acons) is just like @('acons'), and
 @(tsee hons-get) is similar to @(tsee assoc-equal).  But under the hood, hash
 tables are associated with these alists, and, when a certain <b>discipline</b>
 is followed, these functions execute with hash table speeds.</p>

 <p>What is this discipline?  Each @('hons-acons') operation "steals" the
 hash table associated with the alist that is being extended.  Because of this,
 one must be very conscious of which object is the most recent extension of an
 alist and use that extension exclusively.</p>

 <p>The only penalty for a failure to keep track of the most recent extension
 is a loss of execution speed, not of correctness, and perhaps the annoyance of
 some @(tsee slow-alist-warning)s.</p>

 <p>Maintaining discipline may require careful passing of a fast alist up and
 down through function calls, as with any single threaded object in an
 applicative setting, but there is <b>no syntactic enforcement</b> that insists
 you only use the most recent extension of an alist as there is for single
 threaded objects (@(tsee stobj)s).  Also, even with perfectly proper code,
 discipline can sometimes be lost due to user interrupts and aborts.</p>

 <p>Performance Notes</p>

 <p>See @(see hons-acons) for how the final @(tsee cdr) of a fast alist can be
 used as a size hint or as a name for reports printed by calling @(tsee
 fast-alist-summary).</p>

 <p>The keys of fast alists are always @(see normed).  Why?  In Common Lisp,
 equal-based hashing is relatively slow, so to allow the use of eql-based hash
 tables, @(tsee hons-acons) and @(tsee hons-get) always @(tsee hons-copy) the
 keys involved.</p>

 <p>Since alist keys are frequently atoms, this norming activity may often be
 so fast that you do not need to think about it.  But if you are going to use
 large structures as the keys for your fast alist, this overhead can be
 significant, and you may want to ensure that your keys are normed ahead of
 time.</p>

 <p>There is <b>no automatic mechanism</b> for reclaiming the hash tables that
 are associated with alists.  Because of this, to avoid memory leaks, you
 should call @(tsee fast-alist-free) to remove the hash table associated with
 alists that will no longer be used.</p>")

(defxdoc fast-cert
  :parents (certify-book include-book)
  :short "A mode for faster, but possibly unsound, book certification"
  :long "<p>See @(see certify-book) and @(see include-book) for background on
 certifying and including @(see books).</p>

 <p>By default, @(tsee certify-book) includes a &ldquo;Step 3&rdquo; that does
 a @(see local-incompatibility) check.  That check can be expensive for some
 &ldquo;industrial-size&rdquo; books if there are @(see local) events early in
 the book or in its @(see portcullis) commands.  Fast-cert mode provides a way
 to avoid the @(see local-incompatibility) check.  There are the following two
 drawbacks to using ACL2 with fast-cert mode enabled (as described further
 below).</p>

 <ul>

 <li>It may be unsound!  See Section &ldquo;Unsoundness&rdquo; below.</li>

 <li>Therefore, after a book is certified with fast-cert mode enabled, then any
 subsequent attempt to include that book will consider it to be uncertified
 unless the @(tsee include-book) event is executed with fast-cert mode enabled.
 See Section &ldquo;Effects of fast-cert mode...&rdquo; below.</li>

 </ul>

 @({
 Example Forms:

 (set-fast-cert t state)       ; enter fast-cert active mode
 (set-fast-cert nil state)     ; disable fast-cert mode
 (set-fast-cert :accept state) ; enter fast-cert accept mode

 General Form:

 (set-fast-cert expr state)
 })

 <p>where if @('expr') evaluates to @('val'), then: if @('val') is @('t') then
 fast-cert mode becomes (or remains) active; if @('val') is @('nil'), then
 fast-cert mode becomes (or remains) disabled; and otherwise @('val') must be
 @(':accept').  In the last case, ACL2 behaves as though fast-cert mode is
 disabled &mdash; we also say ``not enabled'' for ``disabled'' &mdash; but
 books can be considered certified even if they were certified with fast-cert
 mode enabled.  We say more about these three modes in Section &ldquo;Fast-cert
 modes&rdquo; below.</p>

 <p>Another way to enter fast-cert mode is to set environment variable
 @('ACL2_FAST_CERT') to a non-empty value before starting ACL2.  The
 case-insensitive value, @('"accept"'), causes @('(set-fast-cert :accept
 state)') to be evaluated at startup; otherwise, a non-empty value causes
 @('(set-fast-cert t state)') to be evaluated at startup.</p>

 <p>We turn now to sections that include those promised above.</p>

 <h3>Fast-cert modes</h3>

 <p>There are the following fast-cert modes.</p>

 <ul>

 <li><b>Active</b>: entered with @('(set-fast-cert t state)').  When ACL2 is in
 this mode, the @(see local-incompatibility) check is skipped when certifying a
 book, and the book's @(see certificate) marks it as a &ldquo;fast-cert
 book&rdquo;.</li>

 <li><b>Disabled</b>: entered with @('(set-fast-cert nil state)'), though this
 is the default mode.  In this mode the usual @(see local-incompatibility)
 checks are performed during book certification, and every fast-cert book (as
 defined just above) is considered to be uncertified.</li>

 <li><b>Accept</b>: entered with @('(set-fast-cert :accept state)').  When ACL2
 is in this mode, @(see local-incompatibility) checks are performed just as
 when fast-cert mode is disabled, but a fast-cert book is treated as certified
 just like any other book.</li>

 </ul>

 <p>Fast-cert mode is considered to be &ldquo;enabled&rdquo; exactly when it is
 not disabled, that is, when fast-cert mode is active or accept.</p>

 <p>The discussion above leaves open the question of whether a book that is
 certified in accept mode is marked as a fast-cert book.  That happens only if
 at least one fast-cert book has been included during the session, either
 before the book's certification began or during evaluation of the book's
 events.</p>

 <p>It is always legal to change fast-cert mode from disabled to enabled (using
 @('set-fast-cert')).  It is legal to change fast-cert mode from enabled to
 disabled provided there has been no attempt during the session to include a
 fast-cert book while fast-cert mode is enabled.</p>

 <h3>Potential for unsoundness</h3>

 <p>Consider the proof of @('nil') constructed by the following two books.</p>

 @({
 ;;; fast-cert-unsound-sub.lisp
 (in-package "ACL2")
 (local (defun f () t))
 (defun g () (f))
 (defthm g-is-t
   (equal (g) t))

 ;;; fast-cert-unsound.lisp
 (in-package "ACL2")
 (defun f () nil)
 (include-book "fast-cert-unsound-sub")
 (thm nil
      :hints (("Goal" :use g-is-t)))
 })

 <p>Now execute the following commands to prove @('nil')!</p>

 @({
 (set-fast-cert t state)
 (certify-book "fast-cert-unsound-sub")
 :u
 (certify-book "fast-cert-unsound")
 })

 <p>To see what went wrong, consider what happens if we try this without first
 evaluating @('(set-fast-cert t state)').  In that case, we can see that an
 attempt to certify @('"fast-cert-unsound-sub"') fails the @(see
 local-incompatibility) check.</p>

 @({
 * Step 3:  That completes the admissibility check.  Each form read
 was an embedded event form and was admissible.  We now retract back
 to the initial world and try to include the book; see :DOC
 local-incompatibility.


 ACL2 Error [Translate] in ( DEFUN G ...):  The symbol F (in package
 "ACL2") has neither a function nor macro definition in ACL2.  Please
 define it.  See :DOC near-misses.  Note:  this error occurred in the
 context (F).
 })

 <p>That is, the attempt in Step 3 to include
 @('"fast-cert-unsound-sub.lisp"') fails the local-incompatibility check
 because the definition of @('f') is @(see local), hence skipped, so the
 definition of @('g') is illegal.  Without the use of fast-cert mode, the
 local-incompatibility check would catch this problem.</p>

 <p>(Technical note: if the book is certified while fast-cert mode is active,
 then when we subsequently include @('"fast-cert-unsound-sub"') when
 fast-cert mode is enabled, there is &mdash; perhaps surprisingly &mdash; no
 error.  That is because the translation (see @(see term)) of the definition of
 @('g') is cached in the book's @(see certificate).)</p>

 <p>Note that unsoundness can occur even when fast-cert is in accept mode, not
 just in active mode.  That's because one may include a book in accept mode
 that was certified in a previous session while fast-cert was in active mode,
 and that book could prove @('nil') as in the example above.  In short,
 unsoundness can occur when fast-cert mode is enabled (i.e., fast-cert is in
 accept or active mode).</p>

 <p>Unsoundness when fast-cert mode is enabled is probably rare in practice.
 But because unsoundness is possible with fast-cert mode enabled, a
 &ldquo;@('TTAG NOTE')&rdquo; message is printed when fast-cert mode is
 enabled, for example as follows when fast-cert mode transitions from disabled
 to active.</p>

 @({
 ACL2 !>(set-fast-cert t state)

 TTAG NOTE: Fast-cert mode is active (see :DOC fast-cert).
  T
 ACL2 !>
 })

 <p>The message above may seem a bit misleading, since there is no actual trust
 tag (ttag) involved.  The &ldquo;@('TTAG NOTE')&rdquo; message is simply
 ACL2's way of conveying that there is a trust issue &mdash; typically with the
 use of @(tsee defttag) but also when entering fast-cert mode.</p>

 <p>We conclude this section by mentioning other potential sources of
 unsoundness when fast-cert mode is enabled.  There are probably yet others,
 but again, it is probably rare for fast-cert mode to exhibit unsoundness.
 These behaviors are due to avoiding the @(see local-incompatibility) check
 during certification when fast-cert mode is active.</p>

 <ul>

 <li>Hidden @(tsee defpkg) events are not recorded in a book's @(see
 certificate) when fast-cert mode is active.  See @(see
 hidden-death-package).</li>

 <li>Information about sub-books that is normally recorded in a @(see
 certificate), including the @(see book-hash) values in the @(see portcullis)
 and the @(see keep), is omitted by certification when fast-cert mode is
 active.  This prevents ACL2 from noticing when sub-books are uncertified or
 have changed since the time of the parent book's certification.</li>

 </ul>

 <p>Here are some necessary checks that may be omitted when the
 local-incompatibility check is skipped.</p>

 <ul>

 <li>A non-local @(see congruence) rule needs its alleged equivalence relation
 to be an equivalence relation non-locally.  Generally this means that the
 supporting @(tsee defequiv) event must be non-local.</li>

 <li>A non-local rule of class @(':')@(tsee meta) or @(':')@(tsee
 clause-processor) needs its evaluators to be evaluators non-locally.</li>

 <li>A @(tsee defattach) event imposes requirements on function symbols to be
 @(see guard)-verified.  So if a @('defattach') event is non-local, each
 necessary guard verification status must hold non-locally.</li>

 </ul>

 <p>Because of potential unsoundness when fast-cert mode is enabled, especially
 as explained in the item above regarding status of books that are included in
 a parent book, it is strongly recommended that you eventually certify your
 collection of books with fast-cert mode disabled.  Otherwise there is no sort
 of guarantee that your proofs are valid!</p>

 <h3>Interactions involving fast-cert mode</h3>

 <ul>

 <li>When a book is successfully certified with fast-cert mode active, its
 @(see certificate) records this fact.  Let's call such a certificate (or book)
 a &ldquo;fast-cert certificate&rdquo; (or &ldquo;fast-cert book&rdquo;);
 otherwise it is a &ldquo;normal&ldquo; certificate (or &ldquo;normal
 book&rdquo;).</li>

 <li>When a book is successfully certified with fast-cert in accept mode, the
 book is a normal book only if no fast-cert book is included before or during
 certification.</li>

 <li>When @('include-book') is performed on a book with a valid fast-cert
 certificate, that book is considered to be certified if fast-cert mode is
 enabled and otherwise is considered to be uncertified.</li>

 <li>When @('include-book') is performed on a book with a valid normal
 certificate, that book is considered to be certified regardless of whether or
 not fast-cert mode is enabled at @('include-book') time.</li>

 <li>When @(see provisional-certification) is used during @('certify-book')
 while fast-cert mode is active, then fast-cert is treated as being in accept
 mode; in particular, the local-incompatibility check) is performed in the
 normal way.</li>

 <li>Normally @('certify-book') warns about functions that have not had their
 @(see guard)s verified.  This message is suppressed when fast-cert mode is
 active, because local @('include-book') forms in the certification world can
 make that message very long.</li>

 <li>When a fast-cert book is included while fast-cert mode is enabled, then
 the rest of that ACL2 session must have fast-cert mode enabled.  This
 restriction guarantees that any book then certified during that session will
 be given a fast-mode certificate.</li>

 <li>It is illegal to call @('set-fast-cert') during @('make-event') expansion
 (see @(see make-event)).  There is also an explicit check to prohibit calls of
 @('set-fast-cert') during @('certify-book'), though that is probably
 unnecessary because of the @('make-event') restriction unless that restriction
 is subverted using a trust tag.</li>

 </ul>

 <p>See @(see fast-cert-anomalies) for some possibly surprising (and more
 obscure) consequences of using fast-cert mode.</p>

 <h3>Fast-cert mode and @(tsee save-exec)</h3>

 <p>The motivation for adding fast-cert mode was to provide faster
 certification based on executables created with @(tsee save-exec).  We
 illustrate with an example, which starts by @(see local)ly including a book
 that brings in many definitions and rules (it may take about a minute to
 include) and then saving an executable.  The initial (non-local)
 @('include-book') forms below might not be necessary for all uses of the
 executable.</p>

 @({
 (include-book "centaur/sv/portcullis" :dir :system)
 (include-book "std/util/define" :dir :system)
 (local (include-book "centaur/sv/top" :dir :system))
 :q
 (save-exec "sv-top" "Locally includes centaur/sv/top")
 })

 <p>Now suppose we want to create a book that is based on a tiny part of what
 is provided by the book included above, as follows (comments omitted
 here).</p>

 @({
 (in-package "SV")

 (define name-p (x)
   :parents (name)
   (or (stringp x)
       (integerp x)
       (eq x :self)
       (and (consp x)
            (eq (car x) :anonymous))))

 (define name-fix ((x name-p))
   :parents (name)
   :returns (xx name-p)
   :hooks nil
   (mbe :logic (if (name-p x) x '(:anonymous))
        :exec x)
   ///
   (defthm name-fix-when-name-p
     (implies (name-p x)
              (equal (name-fix x) x))))
 })

 <p>We now invoke the resulting executable, @('./sv-top').</p>

 @({
 ; Start ./sv-top, then:
 (set-fast-cert t state)
 (certify-book "name" ? t :ttags :all)
 })

 <p>In this little example, the certification time has been cut in half with
 fast-cert mode active.  In many cases the reduction may be less than that, but
 in large industrial examples the reduction might be much, much greater &mdash;
 -- especially when the book contains time-consuming events, in particular
 @('include-book') events.</p>")

(defxdoc fast-cert-anomalies
  :parents (fast-cert)
  :short "Potentially surprising consequences of using @(see fast-cert) mode"
  :long "<p>See @(see fast-cert) for relevant background.  This topic discusses
 some surprises one may encounter when using fast-cert mode.</p>

 <p>When fast-cert mode was developed in February 2023, a call of
 &ldquo;@('make')&rdquo; was made with &ldquo;@('ACL2_FAST_CERT=t')&rdquo; and
 target &ldquo;@('regression-everything')&rdquo;, to certify the @(see
 community-books) with fast-cert mode active.  There were only two
 failures (out of thousands of books), both of which are discussed below along
 with their fixes.  There is no plan to continue to test certification of the
 community books with fast-cert mode enabled, but we expect future failures to
 continue to be rare.</p>

 <h3>Example 1</h3>

 <p>Community book @('system/tests/early-load-of-compiled/ttag.lisp') has
 certified regardless of whether or not fast-cert mode is used.  However, when
 it was certified with fast-cert mode active, a later attempt to include the
 book failed.  That failure was due to the way ACL2 handles raw-Lisp
 redefinition (using a trust tag), as explained in a comment in the book.  To
 avoid this problem, the form @('(set-fast-cert nil state)') is in file
 @('ttag.acl2') in the same directory.  Key events in the book are as follows,
 in this order; the first forces a @(see local-incompatibility) check, and you
 can see comments in @('ttag.lisp') for why that is crucial.</p>

 @({
 (local (defun loc (x) x))

 (defun ttag-f (x)
   (declare (xargs :guard t))
   x)

 ; An assertion is here of (equal (ttag-f 3) 3), to be evaluated during both
 ; certify-book and include-book, basically of the form:
 (make-event ...) ; asserts (equal (ttag-f 3) 3)

 (progn!
  (set-raw-mode t)
  (defun ttag-f (x) (cons x x)))
 })

 <h3>Example 2</h3>

 <p>The second example is rather subtle.  Our starting point is the following,
 from community book
 @('rtl/rel9/support/lib2.delta1/add-new-proofs.lisp').</p>

 @({
 ; Matt K. addition: The following lemma, natp-lamz, is not normally necessary.
 ; But with fast-cert mode active, we need it for the proof of lam1_alt-is-lam1.
 ; See :DOC fast-cert-anomalies if you want an explanation.
 (local
  (defthm natp-lamz
    (natp (lamz a b e))
    :rule-classes :type-prescription))
 })

 <p>To see why this lemma is needed when certifying in fast-cert mode, let us
 start by re-creating the environment where the definition of @('lamz') has
 been introduced.  We assume here that the sub-books that are included were
 certified with fast-cert mode active.</p>

 @({
 (set-fast-cert t state) ; so that sub-books are included as certified
 (ld "rtl/rel9/support/lib2.delta1/add-new-proofs.lisp"
     :dir :system
     ;; to speed things up:
     :ld-skip-proofsp t)
 })

 <p>We see that the built-in @(see type-prescription) rule for @('lamz') says
 only that @('lamz') returns a rational number, not necessarily a non-negative
 integer.</p>

 @({
 ACL2 !>:pr lamz

 Rune:         (:TYPE-PRESCRIPTION LAMZ)
 Enabled:      T
 Hyps:         T
 Term:         (LAMZ A B E)
 Backchain-limit-lst: NIL
 Basic-ts:     *TS-RATIONAL*
 Vars:         NIL
 Corollary:    (RATIONALP (LAMZ A B E))

 ...
 })

 <p>If we do the same experiment when sub-books were certified with fast-cert
 mode disabled, the @(':')@(tsee pr) output will instead show a built-in @(see
 type-prescription) rule for @('lamz') saying that @('lamz') returns a
 non-negative integer.  This discrepancy in that built-in rule explains why the
 additional lemma above, @('natp-lamz'), was necessary when certifying the
 @(see community-books) with fast-cert mode active.</p>

 <p>So now let us investigate why certifying books with fast-cert mode active
 weakens the built-in type-prescription rule for @('lamz').  After running the
 @('set-fast-cert') and @(tsee ld) commands displayed above, we see where
 @('lamz') is defined.</p>

 @({
 ACL2 !>:pe lamz
    d       2  (LOCAL (INCLUDE-BOOK "../lib2/top"))
               
               [Included books, outermost to innermost:
                "/Users/kaufmann/acl2/acl2/books/rtl/rel9/support/lib2/top.lisp"
                "/Users/kaufmann/acl2/acl2/books/rtl/rel9/support/lib2/add.lisp"
               ]
               
 >L             (DEFUN LAMZ (A B E)
                       (LNOT (LIOR A (LNOT B (1+ E)) (1+ E))
                             (1+ E)))
 ACL2 !>
 })

 <p>But we need to work harder to find the real source of the definition of
 @('lamz').  In @('rtl/rel9/support/lib2/add.lisp') we see that the definition
 of @('lamz') is preceded by @('(set-enforce-redundancy t)') as well as
 @('(local (include-book "base"))').  When we invoke @(':ubt 1') and then
 @('(include-book "base")'), we can evaluate @(':pe lamz') to see that
 @('lamz') is defined in @('rtl/rel9/support/lib1/add.lisp'), which contains
 @('(set-enforce-redundancy t)') and the local event, @('(local (include-book
 "../support/top"))').  So we include <i>that</i> book after invoking @(':ubt
 1'), then (again) invoke @(':pe lamz'), and finally find the true source of
 the definition of @('lamz'): @('rtl/rel9/support/support/lextra.lisp').</p>

 <p>So now consider what happens when we start ACL2 and evaluate the following
 commands.  For now, assume that we have used ACL2 fast-cert mode disabled to
 certify all books being included.  We use @(':ld-skip-proofsp 'include-book')
 to simulate what happens when including the book.</p>

 @({
 ; with fast-cert mode disabled
 (ld "rtl/rel9/support/support/lextra.lisp"
     :dir :system
     :ld-skip-proofsp 'include-book)
 :ubt lamz
 (defun lamz (a b e)
   (lnot (lior a (lnot b (1+ e)) (1+ e)) (1+ e)))
 })

 <p>Then @(':pr lamz') shows a @(':type-prescription') rule for @('lamz') that
 this function returns a non-negative integer.  That is explained in part by
 the following output, which mentions a rule stating that @('lnot') returns a
 non-negative integer, which was used to compute the built-in type for
 @('lamz') that it returns a non-negative integer.</p>

 @({
 We used the :type-prescription rule LNOT-NONNEGATIVE-INTEGER-TYPE.
 })

 <p>Now repeat the same experiment but where we assume that fast-cert mode has
 been active for all book certification and we start with @('(set-fast-cert t
 state)').  This time there is no such output about
 @('LNOT-NONNEGATIVE-INTEGER-TYPE').  Aha!  The culprit is the following form
 near the top of @('"rtl/rel9/support/support/lextra.lisp"').</p>

 @({
 (local (in-theory (current-theory 'lextra0-start)))
 })

 <p>That form disables the @(':type-prescription') rule
 @('LNOT-NONNEGATIVE-INTEGER-TYPE'), which is necessary for computing a
 non-negative integer (i.e., @('natp')) type for the built-in
 @(':type-prescription') rule for @('lamz').  By contrast, without fast-cert
 mode active, the world is rolled back past local events for the
 local-incompatibility check, and then when events in the book are processed
 during the @('include-book') phase of certification, the rule
 @('LNOT-NONNEGATIVE-INTEGER-TYPE') is available for computing the built-in
 type-prescription for @('lamz'), which is stored in the book's @(see
 certificate).  But with fast-cert mode active, the world is not rolled back,
 so the built-in type-prescription for lamz remains as originally computed,
 where the rule @('LNOT-NONNEGATIVE-INTEGER-TYPE') is disabled.</p>

 <p>Indeed, if you read the certificate file for the @('lextra.lisp') book
 above, you'll see that the @(':TYPE-PRESCRIPTION') entry for @('lamz')
 indicates a rational type when books are certified with fast-cert mode active
 but a non-negative integer type when certified with fast-cert mode disabled.
 You can read that certificate file as follows.</p>

 @({
 (read-file (concatenate 'string
                         (system-books-dir state)
                         "rtl/rel9/support/support/lextra.cert")
            state)
 })")

(defxdoc fc-report
  :parents (forward-chaining-reports)
  :short "To report on the forward chaining activity in the most recent proof"
  :long "@({
  Example: (fc-report 15)

  General Form: (fc-report k)
 })

 <p>where @('k') is the number of some forward chaining report printed in the
 most recent event.</p>

 <p>See @(see forward-chaining-reports) for details.</p>")

(defxdoc fifth
  :parents (nth acl2-built-ins)
  :short "Fifth member of the list"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc file-length$
  :parents (io)
  :short "The size of a file in bytes"
  :long "<p>This analogue of the Common Lisp function, @('file-length'), uses
 that function under the hood to compute efficiently the number of bytes @('B')
 in the specified file if that number can be determined, returning @('(mv B
 state)'); otherwise it returns @('(mv nil state)').  The @(tsee guard) of
 @('file-length$') requires that the first argument is a string; the second
 argument is the ACL2 @(tsee state).  The logical definition does not actually
 look at the file and hence is not useful for reasoning about the number of
 bytes in the file.</p>

 @(def file-length$)")

(defxdoc file-reading-example
  :parents (tutorial5-miscellaneous-examples)
  :short "Example of reading files in ACL2"
  :long "<p>This example illustrates the use of ACL2's @(see IO) primitives to
 read the forms in a file.  See @(see io).</p>

 <p>This example provides a solution to the following problem.  Let's say that
 you have a file that contains s-expressions.  Suppose that you want to build a
 list by starting with @('nil'), and updating it ``appropriately'' upon
 encountering each successive s-expression in the file.  That is, suppose that
 you have written a function @('update-list') such that @('(update-list obj
 current-list)') returns the list obtained by ``updating'' @('current-list')
 with the next object, @('obj'), encountered in the file.  The top-level
 function for processing such a file, returning the final list, could be
 defined as follows.  Notice that because it opens a channel to the given file,
 this function modifies @(see state) and hence must return @(see state).  Thus
 it actually returns two values: the final list and the new @(see state).</p>

 @({
    (defun process-file (filename state)
      (mv-let
       (channel state)
       (open-input-channel filename :object state)
       (mv-let (result state)
               (process-file1 nil channel state) ;see below
               (let ((state (close-input-channel channel state)))
                 (mv result state)))))
 })

 <p>The function @('process-file1') referred to above takes the currently
 constructed list (initially, @('nil')), together with a channel to the file
 being read and the @(see state), and returns the final updated list.  Notice
 that this function is tail recursive.  This is important because many Lisp
 compilers will remove tail recursion, thus avoiding the potential for stack
 overflows when the file contains a large number of forms.</p>

 @({
    (defun process-file1 (current-list channel state)
      (mv-let (eofp obj state)
              (read-object channel state)
              (cond
               (eofp (mv current-list state))
               (t (process-file1 (update-list obj current-list)
                                 channel state)))))
 })

 <p>As an exercise, you might want to add @(see guard)s to the functions above
 and verify the guards (see @(see verify-guards)).  See @(see args) or make a
 call of the form @('(guard 'your-function nil (w state))') to see the guard of
 an existing function.</p>")

(defxdoc file-write-date$
  :parents (io)
  :short "The write-date of a file as a natural number"
  :long "<p>This analogue of the Common Lisp function, @('file-write-date'),
 uses that function under the hood to compute the write date @('D') as a
 natural number if the write date can be determined, returning @('(mv D
 state)'); otherwise it returns @('(mv nil state)').  That number is, quoting
 the Common Lisp HyperSpec, the number of seconds ``measured as an offset from
 the beginning of the year 1900 (ignoring leap seconds)''.  The @(tsee guard)
 of @('file-write-date$') requires that the first argument is a string; the
 second argument is the ACL2 @(tsee state).  The logical definition does not
 actually look at the file and hence is not useful for reasoning about the
 write date.</p>

 <p>This utility provides a reasonable way to determine whether a file exists,
 like Common Lisp's @('probe-file'), according to whether @('D') is
 non-@('nil') in when @('(mv D state)') is returned.</p>

 @(def file-write-date$)")

(defxdoc finalize-event-user
  :parents (output-controls)
  :short "User-supplied code to complete @(see events), e.g., with extra @(see
 summary) output"
  :long "<p>This utility is intended for system hackers, not standard ACL2
 users.</p>

 <p>ACL2 prints summaries at the conclusions of processing @(see events)
 (unless summaries are inhibited; see @(see set-inhibit-output-lst) and also
 see @(see set-inhibited-summary-types)).  You may arrange for processing to
 take place just after the @(see summary), by defining a function with argument
 list @('(ctx body state)') that returns one value, namely @('state').  We
 describe @('ctx') and @('body') at the end below, but you may simply prefer to
 ignore these arguments.)  Your function should normally be a @(see
 guard)-verified @(':')@(tsee logic) mode function with no guard other than
 that provided by the input requirement on @(tsee state), that is, @('(state-p
 state)'); but later below we discuss how to avoid this requirement.  You then
 attach (see @(see defattach)) your function to the function
 @('finalize-event-user').  The following example illustrates how this all
 works.</p>

 @({
  (defun finalize-event-user-test (ctx body state)
    (declare (xargs :stobjs state)
             (ignore ctx body))
    (cond ((and (boundp-global 'abbrev-evisc-tuple state)
                (open-output-channel-p *standard-co*
                                       :character
                                       state))
           (pprogn
            (if (eq (f-get-global 'abbrev-evisc-tuple state) :DEFAULT)
                (princ$ "Abbrev-evisc-tuple has its default value."
                        *standard-co*
                        state)
              (princ$ "Abbrev-evisc-tuple has been modified."
                      *standard-co*
                      state))
            (newline *standard-co* state)))
          (t state)))

  (defattach-system finalize-event-user finalize-event-user-test)
 })

 <p>After admission of the two events above, an event @(see summary) will
 conclude with extra printout, for example:</p>

 @({
  Note: Abbrev-evisc-tuple has its default value.
 })

 <p>If the attachment function (above, @('finalize-event-user-test')) does not
 meet all the requirements stated above, then you can use the @(':skip-checks')
 argument of @(tsee defattach) to get around the requirement, as illustrated by
 the following example.</p>

 @({
  (defun finalize-event-user-test2 (ctx body state)
    (declare (xargs :stobjs state
                    :mode :program)
             (ignore ctx body))
    (observation
     'my-test
     "~|Value of term-evisc-tuple: ~x0~|"
     (f-get-global 'term-evisc-tuple state)))

  (defttag t) ; needed for :skip-checks t

  (defattach-system (finalize-event-user finalize-event-user-test2)
    :skip-checks t)
 })

 <p>So for example:</p>

 @({
  ACL2 !>(set-term-evisc-tuple (evisc-tuple 2 7 nil nil) state)
   (:TERM)
  ACL2 !>(defconst *foo6* '(a b c))

  Summary
  Form:  ( DEFCONST *FOO6* ...)
  Rules: NIL
  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)

  ACL2 Observation in MY-TEST:
  Value of term-evisc-tuple: (NIL 2 7 NIL)
   *FOO6*
  ACL2 !>
 })

 <p>Note that (as of this writing) the macro @(tsee observation) expands to a
 call of a @(':')@(tsee program)-mode function.  Thus, the trick shown above
 involving @(':skip-checks') allows the use of @(':program')-mode functions;
 for example, you can print with @(tsee fmt).</p>

 <p>See community book @('books/misc/defattach-bang.lisp') for a variant of
 @(tsee defattach) that uses @(tsee ec-call) to avoid issues of @(see guard)
 verification.</p>

 <p>Also see @(see initialize-event-user), which discusses the handling of
 @(see state) globals by that utility as well as by
 @('finalize-event-user').</p>

 <p>Finally, as promised above, we briefly describe the arguments @('ctx') and
 @('body').  These are the arguments passed to the call of macro
 @('with-ctx-summarized') under which @('finalize-event-user') (or
 @('initialize-event-user')) was called.  Thus, they are unevaluated
 expressions.  For example, system function @('defthm-fn1') has a body of the
 following form.</p>

 @({
  (with-ctx-summarized
   (cons 'defthm name)
   (let ((wrld (w state))
         (ens (ens state))
         .....
 })

 <p>Thus, when @('initialize-event-user') and @('finalize-event-user') are
 called on behalf of @(tsee defthm), @('ctx') is the s-expression</p>

 @({
  (cons 'defthm name)
 })

 <p>while @('body') is the following s-expression (with most code elided).</p>

 @({
   (let ((wrld (w state))
         (ens (ens state))
         .....
 })

 <p>You might find it helpful to use @(tsee trace$) to get a sense of @('ctx')
 and @('body'), for example, @('(trace$ finalize-event-user)').</p>")

(defxdoc find-rules-of-rune
  :parents (rune)
  :short "Find the rules named rune"
  :long "@({
  General Form:
  (find-rules-of-rune rune wrld)
 })

 <p>This function finds all the rules in @('wrld') with @(':')@(tsee rune)
 rune.  It returns a list of rules in their internal form (generally as
 described by the corresponding @('defrec')).  Deciphering these rules is
 difficult since one cannot always look at a rule object and decide what kind
 of record it is without exploiting many system invariants (e.g., that
 @(':')@(tsee rewrite) runes only name rewrite-rules).</p>

 <p>At the moment this function returns @('nil') if the rune in question is a
 @(':')@(tsee refinement) rune, because there is no object representing
 @(':')@(tsee refinement) rules.  (@(':')@(tsee refinement) rules cause changes
 in the @(''coarsenings') properties.)  In addition, if the rune is an
 @(':')@(tsee equivalence) rune, then congruence rules with that rune will be
 returned &mdash; because @(':')@(tsee equivalence) lemmas generate some
 congruence rules &mdash; but the fact that a certain function is now known to
 be an equivalence relation is not represented by any rule object and so no
 such rule is returned.  (The fact that the function is an equivalence relation
 is encoded entirely in its presence as a @(''coarsening') of @(tsee
 equal).)</p>")

(defxdoc finding-documentation
  :parents (documentation)
  :short "Searching the documentation"
  :long "<p>The @(':')@(tsee doc) command will display, at the terminal, @(see
 documentation) topics defined in ACL2 or in @(see books) that have already
 been included.  But how can you find documentation for books that are not
 included in the current ACL2 session?</p>

 <p>The @(see xdoc) @(`(:raw (combined-manual-ref))`) includes documentation
 for both the ACL2 system and the @(see community-books).  For more information
 on this manual and how to view it, see @(see documentation).</p>")

(defxdoc first
  :parents (nth acl2-built-ins)
  :short "First member of the list"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc fix
  :parents (numbers acl2-built-ins)
  :short "Coerce to a number"
  :long "<p>@('Fix') simply returns any numeric argument unchanged, returning
 @('0') on a non-numeric argument.  Also see @(see nfix), see @(see ifix), and
 see @(see rfix) for analogous functions that coerce to a natural number, an
 integer, and a rational number, respectively.  See @(see the-number) for a
 variant of @('fix') whose guard specifies a numeric argument.</p>

 <p>@('Fix') has a @(see guard) of @('t').</p>

 @(def fix)")

(defxdoc fix-true-list
  :parents (lists acl2-built-ins)
  :short "Coerce to a true list"
  :long "<p>@('Fix-true-list') is a macro that expands to a call of @(tsee
  true-list-fix) with the same argument.</p>

 @(def fix-true-list)")

(defxdoc flet
  :parents (basics acl2-built-ins)
  :short "Local binding of function symbols"
  :long "<p>See @(see macrolet) for an analogous utility for defining macros
 locally.</p>

 @({
 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)
 })

 <p>where @('body') is a term, and each @('defi') is a definition as in @(tsee
 defun) but with the leading @('defun') symbol omitted.  See @(see defun), but
 see @(see declare) for the declarations permitted directly under the
 @('defi').  On the other hand, regarding the @('declare-formi') (if any are
 supplied): 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').</p>

 <p>The innermost @('flet') or @(tsee macrolet) binding of a symbol, @('f'),
 above a call of @('f'), is the one that provides the definition of @('f') for
 that call.  Note that neither @('flet') nor @('macrolet') provide recursion:
 that is, the definition of @('f') in an @('flet') or @('macrolet') binding of
 @('f') is ignored in the body of that binding.  Consider the following
 example.</p>

 @({
  ; 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))
 })

 <p>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)').</p>

 <p>Although @('flet') behaves in ACL2 essentially as it does in Common Lisp,
 ACL2 imposes the following restrictions and qualifications.</p>

 <ul>

 <li>Every @(tsee declare) form for a local definition (@('def1') through
 @('defk'), above) must be an @('ignore'), @('ignorable'), or @('type')
 expression.  Such @('type') declarations affect evaluation and @(see
 guard)-checking in a way that is completely analogous to such declarations
 that occur between the formal parameters and the body in a @(tsee defun)
 form.</li>

 <li>Each @('defi') must bind a different function symbol.</li>

 <li>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.</li>

 <li>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.)</li>

 <li>If the @('flet')-binding @('defi') is in the body of a function @('f'),
 then the @(see stobj) inputs for @('defi') are implicitly those of its inputs
 that are declared @(see stobj) inputs of @('f').</li>

 <li>When an expression @('(flet (... defi ...) ...)') occurs in the body of a
 @('DO') @(tsee loop$) expression, nevertheless constructs such as @('PROGN')
 and @('SETQ') that ACL2 permits in @('DO') @('loop$') bodies are not permitted
 in @('defi') (unless they occur within the scope of a @('DO') @('loop$')
 expression in that body).  (This restriction is only for ACL2; for example, it
 may be reasonable to call @('RETURN') in such situations but ACL2 does not
 allow that.)</li>

 </ul>

 <p>@('Flet') bindings are evaluated in parallel.  Consider the following
 example.</p>

 @({
  (defun f (x) x)
  (flet ((f (x) (cons x x))
         (g (x) (f x)))
    (g 3))
 })

 <p>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)').</p>

 @({
  (defun f (x) x)
  (flet ((f (x) (cons x x)))
    (flet ((g (x) (f x)))
      (g 3)))
 })

 <p>Under the hood, ACL2 translates @('flet') bindings to @(tsee lambda)
 expressions (see @(see term)), throwing away the @('inline') and
 @('notinline') declarations (if any).  The following example illustrates this
 point.</p>

 @({
  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 !>
 })

 <p>@('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:</p>

 @({
  (defun f (x) x)
  (defun g (x) (f x))
  (defun h (x)
    (flet ((f (x) (cons x x)))
      (g x)))
 })

 <p>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').</p>")

(defxdoc floor
  :parents (numbers acl2-built-ins)
  :short "Division returning an integer by truncating toward negative infinity"
  :long "@({
  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
 })

 <p>@('(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').</p>

 <p>The @(see guard) for @('(floor i j)') requires that @('i') and @('j') are
 rational (@(see real), in ACL2(r)) numbers and @('j') is non-zero.</p>

 <p>@('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, that is, the quotient of the
 division, while the remainder is returned by @(tsee mod).</p>

 @(def floor)")

(defxdoc flush-compress
  :parents (arrays acl2-built-ins)
  :short "Flush the under-the-hood array for the given name"
  :long "@({
  Example Form:
  (flush-compress 'my-array)

  General Form:
  (flush-compress name)
 })

 <p>where @('name') is a symbol.</p>

 <p>Recall that @('(compress1 nm alist)') associates an under-the-hood raw Lisp
 one-dimensional array of name @('nm') with the given association list,
 @('alist'), while @('(compress2 nm alist)') is the analogous function for
 two-dimensional arrays; see @(see compress1) and see @(see compress2).  The
 only purpose of @('flush-compress'), which always returns @('nil'), is to
 remove the association of any under-the-hood array with the given name, thus
 eliminating slow array accesses (see @(see slow-array-warning)).  It is not
 necessary if the return values of @(tsee compress1) and @(tsee compress2) are
 always used as the ``current'' copy of the named array, and thus
 @('flush-compress') should rarely, if ever, be needed in user
 applications.</p>

 <p>Nevertheless, we provide the following contrived example to show how
 @('flush-compress') can be used to good effect.  Comments have been added to
 this log to provide explanation.</p>

 @({
  ACL2 !>(assign a (compress1 'demo
                              '((:header :dimensions (5)
                                         :maximum-length 15
                                         :default uninitialized
                                         :name demo)
                                (0 . zero)
                                (1 . one))))
   ((:HEADER :DIMENSIONS (5)
             :MAXIMUM-LENGTH
             15 :DEFAULT UNINITIALIZED :NAME DEMO)
    (0 . ZERO)
    (1 . ONE))
  ACL2 !>(aref1 'demo (@ a) 0)
  ZERO
  ; As expected, the above evaluation did not cause a slow array warning.  Now
  ; we associate a different under-the-hood array with the name 'demo.
  ACL2 !>(compress1 'demo
                    '((:header :dimensions (5)
                               :maximum-length 15
                               :default uninitialized
                               :name demo)
                      (0 . zero)))
  ((:HEADER :DIMENSIONS (5)
            :MAXIMUM-LENGTH
            15 :DEFAULT UNINITIALIZED :NAME DEMO)
   (0 . ZERO))
  ; The following array access produces a slow array warning because (@ a) is
  ; no longer associated under-the-hood with the array name 'demo.
  ACL2 !>(aref1 'demo (@ a) 0)

  **********************************************************
  Slow Array Access!  A call of AREF1 on an array named
  DEMO is being executed slowly.  See :DOC slow-array-warning
  **********************************************************

  ZERO
  ; Now we associate under-the-hood, with array name 'demo, an alist equal to
  ; (@ a).
  ACL2 !>(compress1 'demo
                    '((:header :dimensions (5)
                               :maximum-length 15
                               :default uninitialized
                               :name demo)
                      (0 . zero)
                      (1 . one)))
  ((:HEADER :DIMENSIONS (5)
            :MAXIMUM-LENGTH
            15 :DEFAULT UNINITIALIZED :NAME DEMO)
   (0 . ZERO)
   (1 . ONE))
  ; The following array access is still slow, because the under-the-hood array
  ; is merely associated with a copy of (@ a), not with the actual object
  ; (@ a).
  ACL2 !>(aref1 'demo (@ a) 0)

  **********************************************************
  Slow Array Access!  A call of AREF1 on an array named
  DEMO is being executed slowly.  See :DOC slow-array-warning
  **********************************************************

  ZERO
  ; So we might try to fix the problem by recompressing. But this doesn't
  ; work.  It would work, by the way, if we re-assign a:
  ; (assign a (compress1 'demo (@ a))).  That is why we usually will not need
  ; flush-compress.
  ACL2 !>(compress1 'demo (@ a))
  ((:HEADER :DIMENSIONS (5)
            :MAXIMUM-LENGTH
            15 :DEFAULT UNINITIALIZED :NAME DEMO)
   (0 . ZERO)
   (1 . ONE))
  ACL2 !>(aref1 'demo (@ a) 0)

  **********************************************************
  Slow Array Access!  A call of AREF1 on an array named
  DEMO is being executed slowly.  See :DOC slow-array-warning
  **********************************************************

  ZERO
  ; Finally, we eliminate the warning by calling flush-compress before we call
  ; compress1.  The call of flush-compress removes any under-the-hood
  ; association of an array with the name 'demo.  Then the subsequent call of
  ; compress1 associates the object (@ a) with that name.  (Technical point:
  ; compress1 always associates the indicated name with the value that it
  ; returns.  In this case, what compress1 returns is (@ a), because (@ a) is
  ; already, logically speaking, a compressed array1p (starts with a :header
  ; and the natural number keys are ordered).
  ACL2 !>(flush-compress 'demo)
  NIL
  ACL2 !>(compress1 'demo (@ a))
  ((:HEADER :DIMENSIONS (5)
            :MAXIMUM-LENGTH
            15 :DEFAULT UNINITIALIZED :NAME DEMO)
   (0 . ZERO)
   (1 . ONE))
  ACL2 !>(aref1 'demo (@ a) 0)
  ZERO
  ACL2 !>
 })

 @(def flush-compress)")

(defxdoc flush-hons-get-hash-table-link
  :parents (fast-alist-free acl2-built-ins)
  :short "Deprecated feature"
  :long "<p>Deprecated.  Alias for @(tsee fast-alist-free).</p>")

(defxdoc fms
  :parents (io acl2-built-ins)
  :short "@('(fms str alist co-channel state evisc) => state')"
  :long "<p>See @(see fmt) for further explanation, including documentation of
 the tilde-directives.</p>")

(defxdoc fms!
  :parents (io acl2-built-ins)
  :short "@('(fms! str alist co-channel state evisc) => state')"
  :long "<p>This function is nearly the same as @(tsee fms), but @('fms!')
 avoids inserting backslash (\) characters when forced to print past the right
 margin.  Use @('fms!') if you want to be able to read the forms back in.</p>")

(defxdoc fmt
  :parents (io acl2-built-ins)
  :short "Formatted printing"
  :long "<p>ACL2 provides the functions @('fmt'), @(tsee fmt1), and @(tsee fms)
 as substitutes for Common Lisp's @('format') function.  Also see @(see fmt!),
 see @(see fmt1!), and see @(see 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 @(tsee state) as an
 argument; see @(see printing-to-strings).  A convenient macro, @('fmx'), is
 described below; also see @(see cw) and see @(see fmx-cw).</p>

 <p>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., @(tsee
 *standard-co*)).</p>

 @({
  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)
 })

 <p>@(tsee Fms) and @('fmt') print an initial newline to put @('channel') in
 column @('0'); @(tsee 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 @(see characters) printed since the last newline.)  The @('col')
 returned by @('fmt') and @(tsee 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 @(see evisc-tuple).</p>

 <p>We list the tilde-directives below.  The notation is explained after the
 chart.</p>

 @({
  ~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
  ~Sx  same as ~s, except that margins are ignored (hence no breaking on
       hyphens and no breaking when the column exceeds the value of
       the hard right-margin)
  ~    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 right margin, output a hyphen and newline; else
       skip this char
 })

 <p>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.</p>

 @({
  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 !>
 })

 <p>Note: @('~p'), @('~q'), @('~P'), and @('~Q') are also currently supported,
 but are deprecated and generally avoided in this manual.  These are
 respectively the same as @('~x'), @('~y'), @('~X'), and @('~Y'), except that
 their arguments may be expected to be terms, preferably
 untranslated (user-level) terms, since at one time there was the possibility
 that they could be printed using infix notation in certain environments.
 Infix printing is no longer supported, however.</p>

 <p>ACL2's formatting functions print to the indicated channel, keeping track
 of which column they are in.  @(tsee Fmt1) can be used if the caller knows
 which column the channel is in (i.e., how many @(see characters) have been
 printed since the last newline).  Otherwise, @('fmt') or @(tsee 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*')), except when using @('~S').  See @(see
 set-fmt-hard-right-margin) for a discussion of how linebreaks are inserted and
 how to change the relevant default settings.  A right margin of 40 is used for
 pretty printing with @('~y'), @('~Y'), @('~q'), and @('~Q') and can be changed
 to a positive integer @('N') with @('(set-ppr-flat-right-margin N
 state)').</p>

 <p>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 @(see characters)
 immediately following the tilde.  The typical tilde-directive is a group of
 three successive @(see 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, @(see
 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.</p>

 <p>It should be noted that this use of @(see 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.</p>

 <p>The following text contains examples that can be evaluated.  To make this
 process easier, we use a macro, @('fmx').  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; for similar utilities that do not
 take or return @(see state), see @(see cw) and @(see fmx-cw).  The variables
 used are @('#\0') through @('#\9').  The macro constructs an appropriate
 alist, @('a'), and then evaluates @('(fmt` str a 0 *standard-co* state
 nil)').</p>

 <p>Thus,</p>

 @({
  (fmx "~%Here is v0, ~x0, and here is v1, ~x1."
       (cons 'value 0)
       (cons 'value 1))
 })

 <p>is just an abbreviation for</p>

 @({
  (fmt1 "~%Here is v0, ~x0, and here is v1, ~x1."
        (list (cons #\0 (cons 'value 0))
              (cons #\1 (cons 'value 1)))
        0
        *standard-co*
        state
        nil)
 })

 <p>which returns @('(mv 53 state)') after printing, on a separate line,</p>

 @({
     Here is v0, (VALUE . 0), and here is v1, (VALUE . 1).
 })

 <p>We now devote special attention to three of the tilde-directives whose use
 is non-obvious.</p>

 <p><i>The Case Statement</i></p>

 <p>@('~#x') is essentially a ``case statement'' in the language of @('fmt').
 The proper form of the statement is</p>

 @({
  ~#x~[case-0~/case-1~/ ... ~/case-k~],
 })

 <p>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').</p>

 <p>For example</p>

 @({
  (fmx "Go ~#0~[North~/East~/South~/West~].~%" 1)
 })

 <p>will print ``Go East.'' followed by a newline and will return</p>

 <p>@('(mv 0 state)'), while if you change the @('1') above to @('3') (the
 maximum legal value), it will print ``Go West.''</p>

 <p>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.</p>

 @({
  (let ((cases '(a b c)))
    (fmx "There ~#0~[is ~n1 case~/are ~n1 cases~]."
         cases
         (length cases)))
 })

 <p>will print ``There are three cases.'' but if you change the</p>

 <p>@(''(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.''</p>

 <p><i>Indirection</i></p>

 <p>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,</p>

 @({
  (let ((ev 'DEFUN))
   (fmx "~x0 is an event~@1."
        'foo
        (if (member-eq ev '(defun defstub encapsulate))
            " that may introduce a function symbol"
            "")))
 })

 <p>will print ``@('foo') is an event that may introduce a function symbol,''
 but if the value of @('ev') is changed from @(''')@(tsee defun) to
 @(''')@(tsee 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</p>

 @({
  ~#1~[~/ that may introduce a function symbol~]
 })

 <p>where the value of @('#\1') is appropriately computed to be @('0') or
 @('1').</p>

 <p>If the argument to @('~@') is a pair, it is taken to be a format string
 @(tsee cons)ed 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 @(tsee 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:</p>

 @({
  (cons
    "Error:  The instruction ~x0 is illegal when the stack is ~x1.~%"
    (list (cons #\0 (current-instruction st))
          (cons #\1 (i-stack st))))
 })

 <p>If the @('current-instruction') and @('i-stack') (whatever they are) are
 @(''(popi 3)') and @(''(a b)') when the @(tsee cons) above is evaluated, then
 it produces</p>

 @({
  '("Error:  The instruction ~x0 is illegal when the stack is ~x1.~%"
    (#\0 POPI 3)
    (#\1 A B))
 })

 <p>and if this pair is made the value of the @('fmt') variable @('0'), then
 @('~@0') will print</p>

 @({
     Error:  The instruction (POPI 3) is illegal when the stack is (A B).
 })

 <p>For example, evaluate</p>

 @({
  (let
   ((pair
    '("~%Error:  The instruction ~x0 is illegal when the stack is ~x1.~%"
      (#\0 POPI 3)
      (#\1 A B))))
   (fmx "~@0" pair)).
 })

 <p>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.</p>

 <p>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.</p>

 @({
  (let ((pair '("Error:  The instruction ~x0 ~
                is illegal when the stack is ~
                ~x1.~%"
                (#\0 POPI 3)
                (#\1 A B))))
   (fmx "~%~@0" pair)).
 })

 <p>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.</p>

 <p><i>Iteration</i></p>

 <p>The @('~*') directive is used to process each element of a list.  For
 example,</p>

 @({
  (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
 })

 <p>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 @('~*').</p>

 <p>The @('~*') directive allows the 5-tuple to specify in its final @(tsee
 cdr) an alist with which to extend the current one before processing the
 individual elements.</p>

 <p>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 @('~@').</p>

 <p>Here is a complex example.  In the @(tsee 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.</p>

 @({
  (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))
 })

 <p>This @(tsee let*) prints</p>

 @({
     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.
 })

 <p>You might wish to try evaluating the @(tsee let*) after removing elements
 of phrases.</p>

 <p>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 @(':')@(tsee 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
 @(tsee state).  To see how @('fmt-doc-example') works, @(':')@(tsee pe)
 @('fmt-doc-example').</p>

 @({
  (fmt-doc-example '(a b c d e f g h i j k l m n o p) state)
 })

 <p>will produce the output</p>

 @({
     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.
 })

 <p>and return @('(mv 15 state)').</p>

 <p>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.</p>")

(defxdoc fmt!
  :parents (io acl2-built-ins)
  :short "@('(fmt! str alist co-channel state evisc) => state')"
  :long "<p>This function is nearly the same as @(tsee fmt), but @('fmt!')
 avoids inserting backslash (\) characters when forced to print past the right
 margin.  Use @('fmt!') if you want to be able to read the forms back in.</p>")

(defxdoc fmt-to-comment-window
  :parents (cw io acl2-built-ins)
  :short "Print to the comment window"
  :long "
 @({
  General Form:
  (fmt-to-comment-window fmt-string alist col evisc-tuple print-base-radix)
 })

 <p>where these arguments are as described for @(tsee fmt1) (see @(see fmt))
 except that the last argument is as described for @(tsee
 cw-print-base-radix).</p>

 <p>See @(see cw) for important background.  Calls of the macro @('cw') expand
 to calls of the function @('fmt-to-comment-window') whose final three
 arguments are @('0'), @('nil'), and @('nil').  For variants of
 @('fmt-to-comment-window') that provide readable output (suffix @('"!"'))
 and are never inhibited (suffix @('"+"')), see @(see
 fmt-to-comment-window!), @(see fmt-to-comment-window+), and @(see
 fmt-to-comment-window!+).</p>

 <p>Function @('fmt-to-comment-window') is similar to @('fmt1') (see @(see
 fmt)), except that the channel is @(tsee *standard-co*) and the ACL2 @(tsee
 state) is neither an input nor an output, and moreover, an additional argument
 specifies the print-base and optionally the print-radix.  That additional
 argument is treated the same as the first argument of
 @('cw-print-base-radix'); see @(see cw-print-base-radix).  An analogous
 function, @('fmt-to-comment-window!'), prints with @(tsee fmt!) instead of
 @(tsee fmt), in order to avoid insertion of backslash (\) characters for
 margins; also see @(see cw!), a macro that expands to a call of
 @('fmt-to-comment-window!').  Note that even if you change the value of @(tsee
 ld) special @('standard-co') (see @(see standard-co)),
 @('fmt-to-comment-window') will print to @(tsee *standard-co*), which is the
 original value of @(tsee standard-co).</p>")

(defxdoc fmt-to-comment-window!
  :parents (cw io acl2-built-ins)
  :short "Print readably to the comment window"
  :long "<p>See @(see cw) for important background.</p>

 <p>This is nearly the same as @(tsee fmt-to-comment-window), but
 @('fmt-to-comment-window!') avoids inserting backslash (\) characters when
 forced to print past the right margin.  Use @('fmt-to-comment-window!') if you
 want to be able to read the forms back in.</p>")

(defxdoc fmt-to-comment-window+
  :parents (cw io acl2-built-ins)
  :short "Print uninhibited to the comment window"
  :long "<p>See @(see cw) for important background.</p>

 <p>This is nearly the same as @(tsee fmt-to-comment-window), but
 @('fmt-to-comment-window+') always produces output, even when the @('COMMENT')
 output type is inhibited (see @(see set-inhibit-output-lst)).</p>")

(defxdoc fmt-to-comment-window!+
  :parents (cw io acl2-built-ins)
  :short "Print readably and uninhibited to the comment window"
  :long "<p>See @(see cw) for important background.</p>

 <p>This is nearly the same as @(tsee fmt-to-comment-window), but
 @('fmt-to-comment-window!+') always produces readable output (like @(tsee
 fmt-to-comment-window!)), even when the @('COMMENT') output type is
 inhibited (like @(tsee fmt-to-comment-window+)).</p>")

(defxdoc fmt1
  :parents (io acl2-built-ins)
  :short "@('(fmt1 str alist col co-channel state evisc) => (mv col state)')"
  :long "<p>See @(see fmt) for further explanation, including documentation of
 the tilde-directives.</p>")

(defxdoc fmt1!
  :parents (io acl2-built-ins)
  :short "@('(fmt1! str alist col channel state evisc) => (mv col state)')"
  :long "<p>This function is nearly the same as @(tsee fmt1), but @('fmt1!')
 avoids inserting backslash (\) characters when forced to print past the right
 margin.  Use @('fmt1!') if you want to be able to read the forms back
 in.</p>")

(defxdoc fmx
  :parents (io acl2-built-ins)
  :short "@('(fmx str &rest args) => state')"
  :long "<p>See @(see fmt) for further explanation, including documentation of
 the tilde-directives.</p>")

(defxdoc fmx-cw
  :parents (io acl2-built-ins)
  :short "@('(fmx-cw str &rest args) => state')"
  :long "<p>@('Fmx-cw') is a variant of @('cw'): both take the same arguments
 and have the same behavior on well-formed input, and both return @('nil').
 See @(see cw) for documentation on how to use both utilities.  Unlike @('cw'),
 which has a @(see guard) of @('t'), @('fmx-cw') has a non-trivial guard that
 can catch errors in the use of tilde-directives.  Here is an example of
 such a guard violation, where the corresponding call of @('cw') would instead
 cause a hard error.</p>

 @({
 ACL2 !>(fmx-cw "Hello ~s0." '(world))


 ACL2 Error in TOP-LEVEL:  Guard violation for FMX-CW-FN:
 Illegal Fmt Syntax.  The tilde-s directive at position 6 of the string
 below is illegal because its variable evaluated to (WORLD), which is
 not a symbol, a string, or a number.

 "Hello ~s0."

 ACL2 !>
 })

 <p>Thus, call @('fmx-cw') instead of @('cw') in the body of @(':')@(tsee
 logic) mode definition when you want its @(see guard) verification to help
 ensure the absence of runtime errors from that call.  Note that if you call
 @('fmx-cw') in a definition, the guard proof may benefit from the lemma,
 @('fmx-cw-msg-1-opener'), found in @(see community-book)
 @('books/system/fmx-cw.lisp').</p>

 <p>The variant @('fmx!-cw') avoids the insertion of backslash () characters
 when forced to print past the right margin.  Thus, use @('fmx!-cw') instead of
 @('fmx-cw') if you want the output to be machine-readable.</p>")

(defxdoc fn-equal
  :parents (apply$ defwarrant)
  :short "Equivalence relation on tame functions"
  :long "<p>@('Fn-equal') is an equivalence relation on tame functions.  It
  holds between @('fn1') and @('fn2') iff both are tame functions and
  @('(apply$ fn1 args)') is @('(apply$ fn2 args)'), for all @('args').  A
  @('defun-sk') event is used to express the universally quantified condition.
  @(tsee defwarrant) proves that @('fn-equal') is a congruence relation for
  every argument position of ilk @(':FN').</p>

  <p>Ideally one can substitute one functional object for an equivalent one in
  functional positions.  For example, @('fn-equal') holds between
  <tt>'(LAMBDA (X) X)</tt> and <tt>'IDENTITY</tt>, so one would hold that
  <tt>(collect$ '(LAMBDA (X) X) lst)</tt> could be rewritten to <tt>(collect$
  'IDENTITY lst)</tt> since the first argument of @('collect$') (as defined in
  the @(see introduction-to-apply$)) has ilk @(':FN').  Unfortunately, because
  these are quoted constants, ACL2's rewriter will not rewrite one to the
  other!</p>

  <p>We regard @('fn-equal') as a reminder to us &mdash; or a challenge to
  users!  &mdash; to find a way to handle functional equivalence in the
  rewriter.</p>")

(defxdoc for-loop$
  :parents (loop$)
  :short "Iteration with @(tsee loop$) over an interval of integers or a list"
  :long "<p>This topic assumes that you have read the introduction to
  @('loop$') expressions in ACL2; see @(see loop$).  Here we give more complete
  documentation on @('FOR') @('loop$') expressions, beginning with informal
  discussion and then continuing with detailed syntax (General Form) and
  semantics.  For a discussion of proofs about @('loop$')s, see @(see
  stating-and-proving-lemmas-about-loop$s).</p>

  <p>Examples of @(tsee loop$) expressions, including @('FOR') @('loop$')s, may
  be found in @(see community-book) @('projects/apply/loop-tests.lisp').</p>

  <p>The only allowed iteration clauses are @('IN'), where the variable ranges
  over the elements of the given true list; @('ON'), where the variable ranges
  over the tails of the given true-list; and @('FROM/TO/BY'), where the
  variable ranges over the integers between two bounds, stepping by a positive
  integer increment (or by 1 if no @('BY') clause is provided).</p>

  <p>You may have as many iteration clauses as you wish, connected with
  @('AS').  Each must introduce a unique iteration variable and that variable
  may be optionally followed by an @('OF-TYPE') @(see type-spec) specification.
  @('OF-TYPE') is a Common Lisp feature that allows the compiler to optimize
  operations on the variable in question.  Here is an example.</p>

  @({
  (loop$ for v of-type (and integer (not (satisfies zerop)))
               from 1 to 100
         sum (/ 1 v))
  })

  <p>Here is that same example with a more concise type specification.</p>

  @({
  (loop$ for v of-type (integer 1 *)
               from 1 to 100
         sum (/ 1 v))
  })

  <p>After all of the iteration clauses, you may have a termination test,
  signaled by @('UNTIL'), and/or a conditional test, signaled by @('WHEN').  If
  both are provided, the @('UNTIL') test must come first.  Iteration stops when
  the @('UNTIL') test is satisfied.  The conditional test determines whether
  the loop body is executed for the current value of the iteration
  variables.</p>

  <p>Between the @('UNTIL') symbol and the expression to be tested, and between
  the @('WHEN') symbol and its expression, you may include a @(':GUARD')
  clause.  This is useful if @(see guard) verification requires an invariant
  relating multiple iteration variables.  An example of a guarded @('UNTIL')
  clause is</p>

  @({
  (loop$ for u in lst1 as v in lst2
         until :guard (invariantp u v) (test u v)
         collect (body u v))
  })

  <p>ACL2 supports only five operators in @('FOR') @('loop$')s: @('SUM'),
  @('COLLECT'), @('ALWAYS'), @('THEREIS') and @('APPEND').  We anticipate
  adding other Common Lisp operators eventually.</p>

  <p>The special symbols noted above, sometimes called ``@('FOR') @('loop$')
  keywords'' or just ``@('loop$') keywords'' may be in any package.  These are
  @('FOR'), @('IN'), @('ON'), @('FROM'), @('TO'), @('BY'), @('OF-TYPE'),
  @('WHEN'), @('UNTIL'), @('SUM'), @('COLLECT'), @('ALWAYS'), @('THEREIS'), and
  @('APPEND').</p>

  <p>Between the operator, e.g., @('SUM') or @('COLLECT'), and the
  @('loop$') body you may include a @(':GUARD') clause as in</p>

  @({
  (loop$ for u in lst1 as v in lst2
         collect :guard (invariantp u v) (body u v))
  })

  <p>This is sometimes necessary in the verification of the @(see guard)s for
  the @('loop$') body because Common Lisp's @('OF-TYPE') clauses do not permit
  you to relate one variable to another.</p>

  <p>See @(see lp-section-6) of the @('Loop$') Primer for some exercises in
  writing @('FOR') @('Loop$')s (with answers in a Community Book).  But
  remember to come back here when you get to the end of that section.</p>

  <h3>General Form</h3>

  <p>The syntax of Common Lisp @('loop') expressions is extremely complicated.
  Rather than try to write the abstract syntax of ACL2's @('loop$') expressions
  in the same formal style, we take a different approach, which is workable
  because @('loop$') allows fewer options.</p>

  <p>First we introduce the syntax of a ``target clause,'' a ``type-spec,'' and
  the ``operators.''  Then we describe the most elaborate form of a @('loop$')
  expression in terms of these elements and ordinary ACL2 terms.  Every legal
  @('loop$') expression can be produced by omitting certain optional elements
  from the most elaborate @('loop$') form.  So we conclude the syntactic
  description of @('loop$') by listing the elements that can be omitted.</p>

  <p>A <i>target clause</i> has one of four forms</p>

  <ul>

  <li>@('IN') <i>list-expr</i></li>

  <li>@('ON') <i>expr</i></li>

  <li>@('FROM') <i>lo-expr</i> @('TO') <i>hi-expr</i></li>

  <li>@('FROM') <i>lo-expr</i> @('TO') <i>hi-expr</i> @('BY')
  <i>step-expr</i></li>

  </ul>

  <p>where <i>list-expr</i> is a term (which is expected to evaluate to a true
  list), <i>expr</i> is a term, <i>lo-expr</i> and <i>hi-expr</i> are
  terms (which are expected to evaluate to integers), and <i>step-expr</i> is a
  term (which is expected to evaluate to a positive integer).</p>

  <p>The legal <i>type-specs</i> are listed in @(tsee type-spec).</p>

  <p>The legal <i>operators</i> are @('SUM'), @('COLLECT'), @('ALWAYS'),
  @('THEREIS'), and @('APPEND').</p>

  <p>The most elaborate @('loop$') expression is of the form</p>

  <p>&nbsp; &nbsp; &nbsp; &nbsp; @('(LOOP$ FOR ')<i>v1</i>@(' OF-TYPE ')<i>spec1
  target1</i><br/> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
  &nbsp; &nbsp; &nbsp; &nbsp; @('AS ') &nbsp; <i>v2</i>@(' OF-TYPE ')<i>spec2
  target2</i><br/> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
  &nbsp; &nbsp; &nbsp; &nbsp; ...<br/> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
  &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; @('AS ') &nbsp; <i>vn</i>@('
  OF-TYPE ')<i>specn targetn</i><br/> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
  &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; @('UNTIL :GUARD ')<i>guard1
  until-expr</i><br/> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
  &nbsp; &nbsp; &nbsp; &nbsp; @('WHEN ') &nbsp; @(':GUARD ')<i>guard2
  when-expr</i><br/> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
  &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; ; Note the @('ALWAYS')/@('THEREIS') Exceptions
  below!<br/> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
  &nbsp; &nbsp; &nbsp; <i>op</i>@(' :GUARD ')<i>guard3
  body-expr</i>@(')')<br/></p>

  <p>where each <i>vi</i> &nbsp; is a legal variable symbol and they are all
  distinct, each <i>type-speci</i> &nbsp; is a @(tsee type-spec), each
  <i>targeti</i> &nbsp; is a target clause, each <i>guardi</i>,
  <i>until-expr</i>, and <i>when-expr</i> &nbsp; is a term, <i>op</i> &nbsp; is
  an operator, and <i>body-expr</i> &nbsp; is a term.  Furthermore,
  <i>until-expr</i>, <i>when-expr</i>, and <i>body-expr</i> &nbsp; must be
  @(see tame)!</p>

  <p><i>The @('ALWAYS')/@('THEREIS') Exception:</i> Common Lisp prohibits loops
  with both a @('WHEN') clause and either an @('ALWAYS') or a @('THEREIS')
  operator.  For example, if you are tempted to use @('WHEN') <i>p</i> with
  @('ALWAYS') <i>q</i> you can instead write @('ALWAYS') @('(implies ')<i>p
  q</i>@(')') or, if you want to evaluate @('q') only when @('p') is true, you
  can write @('ALWAYS') @('(if ')<i>p q</i> @('t)').</p>

  <p>The following elements may be omitted.</p>

  <ul>
  <li>any line beginning with @('AS'), @('UNTIL') or @('WHEN'),</li>

  <li>any @('OF-TYPE') <i>speci</i>, and</li>

  <li>any @(':GUARD') <i>guardi</i>.</li>

  </ul>

  <p>As noted above, the @('FOR') @('loop$') keywords (as used above) may be in
  any package.  These are @('FOR'), @('IN'), @('ON'), @('FROM'), @('TO'),
  @('BY'), @('OF-TYPE'), @('WHEN'), @('UNTIL'), @('SUM'), @('COLLECT'),
  @('ALWAYS'), @('THEREIS'), and @('APPEND').</p>

  <p>We give names to certain classes of the syntactic entities above.  The
  <i>v1</i>, ..., <i>vn</i> are called the <i>iteration variables</i>.  The
  <i>spec1</i>, ..., <i>specn</i> are called <i>type specs</i>, each
  corresponds to a certain iteration variable, and each gives rise to a <i>type
  term</i> about its variable in the sense that ``@('X OF-TYPE (SATISFIES
  NATP)')'' gives rise to the type term @('(NATP X)') and ``@('I OF-TYPE
  INTEGER')'' gives rise to the type term @('(INTEGERP I)').  The terms
  involved in the target expressions, e.g., the <i>list-expr</i> and
  <i>expr</i> in ``@('IN') <i>list-expr</i>'' and ``@('ON') <i>expr</i>'' and
  the <i>lo-expr</i>, <i>hi-expr</i> and optional <i>step-expr</i> in the
  ``@('FROM') <i>lo-expr</i> @('TO') <i>hi-expr</i> @('BY') <i>step-expr</i>''
  targets are called <i>target terms</i>.  Finally, the <i>until-expr</i>,
  <i>when-expr</i>, and <i>body-expr</i> are called <i>iterative forms</i>.</p>

  <p>We distinguish the target terms from the iterative forms because they are
  handled very differently at evaluation time.  When a @('loop$') is evaluated,
  the target terms are evaluated just once.  But the iterative forms are
  evaluated multiple times as the iteration variables range over the values of
  the targets.</p>

  <p>A @('FOR') @('loop$') expression with just one iteration variable and in
  which the iterative forms mention no free variable other than the iteration
  variable is called a <i>simple @('loop$')</i> (or, sometimes, a <i>simple
  loop</i>).  An example of a simple loop is</p>

  @({
  (loop$ for x in lst when (evenp x) collect (+ 1 (sq x)))
  })

  <p>A @('FOR') @('loop$') expression is called a <i>fancy @('loop$')</i> if it
  is not simple.  Both of the following @('loop$')s are fancy.</p>

  @({
  (loop$ for x in xlst as y on ylst collect (expr x y))

  (loop$ for x in xlst collect (expr x z))
  })

  <p>The first is fancy because it has two iteration variables.  The second is
  fancy because the body freely uses the variable @('z') which is not the
  iteration variable.  The free variables cannot be @(see stobj)s or @(see
  df)s, since the translation of the @('loop$') will put them into a list; see
  discussion of the semantics, below.  In such cases you may wish to use
  @('DO') @('loop$') expressions (see @(see do-loop$)) instead.</p>

  <h3>Semantics</h3>

  <p>@('FOR') @('loop$') expressions are translated into calls of @(see
  scion)s, with the @('UNTIL') and @('WHEN') clauses translated into
  preprocessors of the targets.  But which scions are used depend on whether
  the loop is simple or fancy.  Recall that a fancy loop is one that has either
  or both of the following characteristics: (a) there is one or more @('as')
  clauses, and/or (b) one of the iterative forms (the @('UNTIL'), @('WHEN') or
  loop body expression) refers to variables other than an iteration variable.
  If the @('loop$') expression is simple, the simple scions are used; otherwise
  the fancy scions are used.</p>

  @({
   loop$               simple          fancy
   keyword             scion           scion
   ______________________________________________
   SUM                 sum$            sum$+
   COLLECT             collect$        collect$+
   ALWAYS              always$         always$+
   THEREIS             thereis$        thereis$+
   APPEND              append$         append$+
   UNTIL               until$          until$+
   WHEN                when$           when$+
   })

  <p>We deal with simple @('loop$')s first.</p>

  <h4>Semantics of Simple Loop$s</h4>

  <p>For example, the simple @('loop$')</p>
  @({
  (loop$ for x in lst collect (+ 1 (sq x)))
  })
  <p>translates to (a term equivalent to)</p>

  @({
  (collect$ (lambda$ (x)
                     (declare (ignorable x))
                     (+ 1 (sq x)))
            lst).
  })

  <p><b>Note:</b> The actual translation is tagged with various markers that
  play a role in evaluation but which are logically irrelevant and which are
  removed during proof.  In this discussion we will not display the marked-up
  translations but logically equivalent terms instead.  You can see the actual
  translations for yourself with @(tsee trans).</p>

  <p>In the translation the target term, @('lst'), appears as an ordinary
  subterm of the translation.  But the iterative form, @('(+ 1 (sq x))'),
  becomes the body of a @(tsee lambda$) expression, which means its translation
  becomes a component of a quoted @('LAMBDA') object.  When the @('collect$')
  is evaluated, the target term is evaluated once but the iterative form is
  evaluated once for each element of the value of the target.</p>

  <p>@('UNTIL') and @('WHEN') clauses are handled by preprocessing the target.
  E.g.,</p>

  @({
  (loop$ for x in lst
         until (> x 100)
         when (evenp x)
         collect (+ 1 (sq x)))
  })

  <p>becomes</p>

  @({
  (collect$ (lambda$ (x)
                     (declare (ignorable x))
                     (+ 1 (sq x)))
            (when$ (lambda$ (x)
                            (declare (ignorable x))
                            (evenp x))
                   (until$ (lambda$ (x)
                                    (declare (ignorable x))
                                    (> x 100))
                           lst)))
  })

  <p>So from a logical perspective, the presence of an @('UNTIL') and/or
  @('WHEN') clause in a @('collect') iteration over @('lst') ``copies'' the
  target value.  The @('until$') copies @('lst') until encountering the first
  element on which its functional argument is true.  The @('when$') then copies
  that (shortened?) target, keeping only the elements that satisfy its
  functional argument.  Finally, the @('collect$') then applies its functional
  argument and collects all the values.</p>

  <p>@('ON') and @('FROM/TO/BY') targets are handled by listing all the
  elements in the given target.  For example,</p>

  @({
  (loop$ for x on lst collect (expr x))
  })

  <p>which maps @('x') over successive non-empty tails of @('lst') and collects
  the value of @('expr') has the logical meaning</p>

  @({
  (collect$ (lambda$ (x) (expr x))
            (tails lst))
  })

  <p>where, for example, @('(tails '(1 2 3))') is @('((1 2 3) (2 3) (3))').</p>

  <p>Spiritually similarly,</p>
  @({
  (loop$ for i from 1 to max by step collect (expr x))
  })

  <p>logically becomes</p>

  @({
  (collect$ (lambda$ (x) (expr x))
            (from-to-by 1 max step))
  })

  <p>where, for example, @('(from-to-by 1 10 2)') is @('(1 3 5 7 9)').</p>

  <p>Similar translations are done for the other operators, e.g., @('SUM') and
  @('ALWAYS').  The advantage of this translation style is that it allows
  compositional reasoning.  We discuss this further below.</p>

  <p>The following example illustrates basic @(see guard) proof obligations, in
  particular showing that @('WHEN') clauses do not help with verifying guards
  for the @('loop$') bodies.  (Similarly, @('UNTIL') clauses do not help
  either.)  The basic problem is that ACL2 requires that @(tsee lambda) objects
  be guard verifiable in isolation, not confined to the context in which a
  particular @('lambda') object appears.  Consider the following.</p>

  @({
  (include-book "projects/apply/top" :dir :system)
  (defun$ sq (n)
    (declare (xargs :guard (natp n)))
    (* n n))
  (defun foo (lst)
    (declare (xargs :guard (nat-listp lst)))
    (loop$ for x of-type (satisfies nat-listp) on lst
           when (consp x)
           sum (sq (car x))))
  })

  <p>Guard verification fails for @('foo').  The summary says that a goal of
  @('NIL') was generated.  Using @(':')@(tsee pso) we can see that the @('NIL')
  goal came from:</p>

  @({
  Subgoal 1.2
  (IMPLIES (NAT-LISTP LOOP$-IVAR)
           (INTEGERP (CAR LOOP$-IVAR))).
  })

  <p>Let's see what is going on by looking at the following simplified
  translation of the @('loop$') expression.</p>

  @({
  (sum$ '(lambda (loop$-ivar)
           (declare (type (satisfies nat-listp) loop$-ivar))
           (sq (car loop$-ivar)))
        (when$ '(lambda ...) (tails lst)))
  })

  <p>Notice that the @('lambda') object supplied to @('sum$') cannot be guard
  verified in isolation: @('nil') satisfies the @(':guard') and @('(car nil)')
  violates the guard of @('sq').  The following modification, which adds a
  @(':guard') directive after the @('SUM') op keyword, solves the problem.</p>

  @({
  (defun foo (lst)
    (declare (xargs :guard (nat-listp lst)))
    (loop$ for x of-type (satisfies nat-listp) on lst
           when (consp x)
           sum :guard (consp x)  ; note new :guard
           (sq (car x))))
  })

  <p>This new @(':guard') may feel redundant, coming as it does after the
  @('when (consp x)') clause.  But it is necessary given the compositional
  semantics.</p>

  <p>A simplified translation of the @('defun') above shows that the
  application @('(sq (car x))') is protected by a suitable guard in the
  @('lambda') object.</p>

  @({
  (sum$ '(lambda (loop$-ivar)
           (declare (type (satisfies nat-listp) loop$-ivar)
                    (xargs :guard (consp loop$-ivar)))
           (sq (car loop$-ivar)))
        (when$ '(lambda ...) (tails lst)))
  })

  <p>Naively we might have expected that the guard proof obligation for the
  @('loop$') body @('(sq (car x))') could assume the @('WHEN') clause, but that
  expectation would be wrong because of the compositional semantics we use and
  the fact that @(tsee lambda) objects must be guard-verifiable on their own.
  The reason for the latter requirement is that our implementation caches
  guard-verified @('lambda') objects for evaluation in raw Lisp, which may take
  place in other contexts different from that in which the @('lambda') first
  appeared.  See @(see print-cl-cache).</p>

  <h4>Semantics of Fancy Loop$s</h4>

  <p>An example of a fancy @('loop$') is</p>

  @({
  (loop$ for x in xlst as y in ylst collect (expr x y z))
  })

  <p>This loop exhibits both characteristics (a) and (b): it has an @('AS')
  clause and the variable @('z') appears in the loop body.  Either
  characteristic is sufficient to classify the loop as fancy.  So fancy scions
  are used.  Here is its semantic counterpart, i.e., its simplified
  translation.</p>

  @({
  (collect$+
   (lambda$ (loop$-gvars loop$-ivars)
            (declare (xargs :guard (and (true-listp loop$-gvars)
                                        (equal (len loop$-gvars) 1)
                                        (true-listp loop$-ivars)
                                        (equal (len loop$-ivars) 2))))
            (let ((z (car loop$-gvars))
                  (x (car loop$-ivars))
                  (y (car (cdr loop$-ivars))))
              (declare (ignorable x y))
              (expr x y z)))
   (list z)
   (loop$-as (list xlst ylst)))
   })

  <p>Before we show the definition of @('collect$+'), note that the arguments
  above to @('collect$+') are (i) a @('lambda$') expression that handles the
  evaluation of the iterative form, in this case @('(expr x y z)'), where
  @('x') and @('y') are iteration variables and @('z') is a ``global'' variable
  not among the iteration variables; (ii) the list of values of the ``global''
  variables, in this case the list containing @('z'); and (iii) a target list
  constructed by @('loop$-as') from the various targets provided in the
  @('loop$'), in this case @('xlst') and @('ylst'), supplying values for
  iteration variables @('x') and @('y') respectively.  For example,
  @('(loop$-as (list '(a b c d e) '(1 2 3)))') is @('((a 1) (b 2) (c 3))').
  These tuples contain successive corresponding values of @('x') and
  @('y').</p>

  <p>The definition of @('collect$+') is essentially</p>
  @({
  (defun collect$+ (fn loop$-gvars lst)
    (if (endp lst)
        nil
        (cons (apply$ fn (list loop$-gvars (car lst)))
              (collect$+ fn loop$-gvars (cdr lst)))))
  })

  <p>We have omitted the guard and an @(tsee MBE) form that make it run more
  efficiently.  All the fancy @('loop$') scions are defined analogously.</p>

  <p>Inspection of the @('lambda$') expression above reveals that it takes a
  list of global variable values and a list of iteration variable values,
  unpacks them with a @('let') that binds the global variables, here just
  @('z'), to their values and binds the iteration variables, here @('x') and
  @('y'), to the corresponding pair of values from the target, and then
  evaluates the @('loop$') body, @('(expr x y z)').</p>

  <p>The names of the formals for the @('lambda$') expressions generated by
  fancy @('loop$') expressions are always @('loop$-gvars') and
  @('loop$-ivars'), for ``@('loop$') global variables'' and ``@('loop$')
  iteration variables.''</p>

  <p>@('UNTIL') and @('WHEN') clauses in a fancy @('loop$') are handled exactly
  as they are in simple @('loop$')s, except that the fancy scions are used
  since the target list is a list of tuples of iteration variable values and
  the @('UNTIL') and @('WHEN') forms may refer to global variables.</p>

  <p>See @(see lp-section-10) of the @('Loop$') Primer for a step-by-step
  discussion of the evaluation of the formal semantics of an example of a fancy
  @('Loop$').  But remember to come back here when you get to the end of that
  section.</p>

  <h4>Special Guard Conjectures for @('FOR') @('loop$')s</h4>

  <p>Since every @('loop$') expands to a call of a @('loop$') scion on a lambda
  object and a target, one would expect that @(see guard) verification would
  generate the guard conjectures for that scion and target.  Indeed, it does.
  In particular, the lambda object must have the correct number of
  formals (which is guaranteed by translation) and the target must satisfy
  @(tsee true-listp).</p>

  <p>But in addition to the expected guard conjectures, we generate some
  special ones for the terms produced by translating @('FOR') @('loop$')
  expressions.  We discuss the reasons in the next section, but here we just
  state what the special conjectures are.  We limit ourselves to a simple
  @('loop$').  Fancy @('loop$')s generalize in the obvious way.  The two
  classes of ``special guard conjectures'' for @('FOR') @('loop$') expressions
  are as follows.</p>

  <ul>

  <li>First, every element (or tail, in the case of @('ON') @('loop$')s))
  satisfies the type-spec, if any, and the @('loop$') body's @(':GUARD'), if
  any.</li>

  <li>Second, the @('loop$') body produces a value acceptable to the @('loop$')
  operator, e.g., the body of a @('SUM') @('loop$') produces a number and
  the body of an @('APPEND') @('loop$') produces a true list.</li>

  </ul>

  <p>See @(see lp-section-8) of the @('Loop$') Primer for some exercises in
  converting recursive functions to guard verified functions using @('FOR')
  @('loop$')s rather than recursion (with answers in a Community Book).  But
  remember to come back here when you get to the end of that section.</p>

  <h4>Discussion of Why LOOP$s Have Special Guards</h4>

  <p>All of the simple @('loop$') scions have the same guard, namely</p>

  @({
  (AND (APPLY$-GUARD FN '(NIL))
       (TRUE-LISTP LST)),
  })

  <p>and all the fancy @('loop$') scions have the same guard, namely</p>

  @({
  (AND (APPLY$-GUARD FN '(NIL NIL))
       (TRUE-LISTP LOOP$-GVARS)
       (TRUE-LIST-LISTP LST)).
  })

  <p>In addition to the normal guard conjectures that would be generated by
  calls of these scions, ACL2 generates some special guard conjectures because
  the normal guard conjectures are insufficient to guarantee the error-free
  execution of the corresponding Common Lisp @('loop') expressions.</p>

  <p>For example, the simplified translation of the body of</p>

  @({
  (defun foo (lst)
    (declare (xargs :guard (foo-guardp lst)))
    (loop$ for x of-type (satisfies spec) on lst sum (expr x)))
  })

  <p>is as follows.  (One might expect the second argument of the @('sum$')
  call to be @('(tails lst)'), and of course that is what it equals, logically;
  the change is to support guards, as discussed in the Technical Note
  below.)</p>

  @({
  (sum$ (lambda$ (loop$-ivar)
                 (declare (type (satisfies spec) loop$-ivar))
                 (expr loop$-ivar))
        (tails (prog2$ (let ((loop$-last-cdr (last-cdr lst)))
                         (declare (type (satisfies spec) loop$-last-cdr))
                         loop$-last-cdr)
                       lst)))
  })

  <p>Prior to the provision for special guards, the normal guard conjectures
  generated for @('foo') would be</p>

  @({
  (and (implies (foo-guardp lst)                                 ; [1]
                (apply$-guard
                 (lambda$ (loop$-ivar)
                   (expr loop$-ivar))
                 '(nil)))
       (implies (foo-guardp lst)                                 ; [2]
                (true-listp (tails lst)))
       (implies (spec loop$-ivar) (expr-guardp loop$-ivar)))     ; [3]
       (implies (foo-guardp lst)                                 ; [4]
                (let ((loop$-last-cdr (last-cdr lst)))
                     (spec loop$-last-cdr)))
  })

  <p>Conjectures [1] and [2] stem from the guard for @('sum$') and establish
  that the guard for @('foo') implies that @('sum$') is passed a function
  object of one argument and a true-list.  Conjecture [3] establishes that the
  guard on the @('lambda$') implies the guard of its body.  Conjecture [4] says
  that the final tail of @('lst') (which is @('nil') if @('lst') is a true
  list; see @(see last-cdr)) satisfies @('spec').  At first [4] may be
  surprising, but inspection of Common Lisp reveals that even though @('(expr
  x)') is never called on the final tail of @('lst'), implementations running
  with high safety settings check that the final tail satisfies @('spec').  If
  you see a runtime guard violation involving variable @('loop$-last-cdr'), you
  can reasonably assume that you are seeing case [4] above.  A guard proof
  failure involving a call of @(tsee last-cdr) may also be from [4].</p>

  <p>(Technical Note.  The production of [4] is accomplished as follows for an
  expression @('(loop for var of-type type-spec on lst ...)'): for the
  translation to a scion call, the target term, @('lst'), is replaced by the
  following expression (simplifying slightly).</p>

  @({
  (prog2$ (let ((loop$-last-cdr (last-cdr lst)))
            (declare (type type-spec loop$-last-cdr))
            loop$-last-cdr)
          lst)
  })

  <p>The @(tsee declare) form causes formula [4] above to be generated as a
  guard proof obligation.  End of Technical Note.)</p>

  <p>The guard proof obligation shown as [4] above, for an expression @('(loop$
  for ... on ...)'), has a variant for an expression @('(loop$ for n from i to
  j by k ...)'), where &ldquo;@('by k')&rdquo; may be implicit if @('k') is
  @('1').  Instead of the requirement in [4] above that the bound variable
  @('loop$-last-cdr') satisfy the @('type-spec'), variables @('loop$-lo'),
  @('loop$-hi'), and @('loop$-by'), which are bound respectively to @('i'),
  @('j'), and @('k'), are required to satisfy the @('type-spec').  A fourth
  requirement is that the last value tested must also satisfy the
  @('type-spec').  That last value tested is @('(+ loop$-lo loop$-by (*
  loop$-by (floor (- loop$-hi loop$-lo) loop$-by)))').  If you see a runtime
  guard violation involving variable @('loop$-lo'), @('loop$-hi'),
  @('loop$-by'), or @('loop$-final'), you can reasonably assume that you are
  seeing this variant of [4].</p>

  <p>But consider the raw Lisp @('loop') generated by the @('loop$') in the raw
  Lisp definition of @('foo'),</p>

  @({
  (loop for x of-type (satisfies spec) on lst sum (expr x)).
  })

  <p>For this @('loop') to execute without error we need to know that [5] every
  non-empty tail of @('lst') satisfies @('spec'), and [6] every non-empty tail
  @('x') of @('lst') is such that @('(expr x)') returns a number.</p>

  <p>So when ACL2's guard verification process encounters a @('sum$') like that
  in the logical @('defun') of @('foo'), it generates two additional guard
  conjectures as described above.  These are as mentioned above: [5] every
  element (or tail) satisfies the type-spec, and [6] the value of the
  @('loop$') body is acceptable to the @('loop$') operator.</p>

  @({
       (implies (and (warrant ...) ; see below                   ; [5]
                     (foo-guardp lst)
                     (member-equal newv (tails lst)))
                (spec newv))

       (implies (and (warrant ...) ; see below                   ; [6]
                     (foo-guardp lst)
                     (member-equal newv (tails lst)))
                (acl2-numberp
                 (apply$ (lambda$ (loop$-ivar) (expr loop$-ivar))
                         (list newv))))
  })

  <p>Notice the addition of hypotheses above of the form @('(warrant ...)').
  ACL2 adds such <i>@(see warrant) hypotheses</i> for function symbols that
  might be @(tsee apply$)'d during evaluation of a scion call (in this case,
  @('sum$')).</p>

  <p>In general, you may notice that ACL2 generates such ``special'' guard
  conjectures for all calls of @('FOR') @('loop$') scions, whether or not they
  stemmed from uses of @('loop$').  @('FROM/TO/BY') targets require that the
  bounds and step all satisfy the @('OF-TYPE') specification, and the
  @('APPEND') operator requires that the loop body generate a @(tsee
  true-listp) (instead of an @(tsee acl2-numberp) as required by the @('SUM')
  operator).</p>

  <h4>The Compromise Between Reasoning and Efficiency</h4>

  <p>The translation of @('loop$') expressions into formal terms reflects a
  compromise between facilitating compositional reasoning and efficient
  execution.</p>

  <p>One sign of that compromise is our use of scions to handle @('UNTIL') and
  @('WHEN') clauses.  As noted above, by translating</p>

  @({
  (loop$ for x in lst until ... when ... collect ...)
  })

  <p>into</p>

  @({
  (collect$ ... (when$ ... (until$ ... lst)))
  })

  <p>we're forcing the evaluation of the formal semantics to copy the target
  twice before collecting.  But it gives us the ability to reason
  compositionally about @('collect$'), @('when$'), and @('until$').  We could
  have defined a version of @('collect$') that took three @('lambda$')
  expressions, one to terminate the collection, one to filter for the elements
  we're interested in, and one to transform those elements into the values we
  wish to collect.  This would avoid copying upon evaluation but make it more
  difficult to reason.</p>

  <p>Another example of compositionality is to consider a simple @('loop$')
  over the @('IN') target @('(append a b)').  There are 8 different ways you
  can do a simple @('COLLECT') over an @('(append a b)') target,</p>

  @({
  (loop$ for x in (append a b) collect (expr x))
  (loop$ for x on (append a b) collect (expr x))
  (loop$ for x in (append a b) until (stop x) collect (expr x))
  (loop$ for x on (append a b) until (stop x) collect (expr x))
  (loop$ for x in (append a b) when (test x) collect (expr x))
  (loop$ for x on (append a b) when (test x) collect (expr x))
  (loop$ for x in (append a b) until (stop x) when (test x)
         collect (expr x))
  (loop$ for x on (append a b) until (stop x) when (test x)
         collect (expr x))
  })

  <p>Similarly, there are 8 ways to @('SUM') over an @('(append a b)') target,
  8 ways to @('APPEND') over an @('(append a b)'), and 4 ways each to
  @('ALWAYS') or @('THEREIS') over an @('(append a b)') target.  Thus, there
  are 32 different simple @('loop$')s over @('(append a b)').  And you can
  arrange to distribute the simple @('loop$') over the @('(append a b)') with
  just seven rewrite rules.</p>

  @({
  (equal (collect$ fn (append a b))
         (append (collect$ fn a)
                 (collect$ fn b)))

  (equal (sum$ fn (append a b))
         (+ (sum$ fn a)
            (sum$ fn b)))

  (equal (always$ fn (append a b))
         (and (always$ fn a)
              (always$ fn b)))

  (equal (thereis$ fn (append a b))
         (or (thereis$ fn a)
             (thereis$ fn b)))

  (equal (append$ fn (append a b))
         (append (append$ fn a)
                 (append$ fn b)))

  (equal (until$ fn (append a b))
         (if (exists$ fn a)
             (until$ fn a)
             (append a (until$ fn b))))

  (equal (when$ fn (append a b))
         (append (when$ fn a)
                 (when$ fn b)))

  })

  <p>Thus, you can reason about @('WHEN') and @('UNTIL') clauses without having
  to consider how they are used in the superior @('loop$') expression.</p>

  <p>To deal with fancy @('loop$') you need seven more rewrite rules, one for
  each fancy @('loop$') scion.  But since every simple @('loop$') can be
  expressed by an appropriate use of fancy scions, we could have translated
  every @('FOR') @('loop$') to fancy scions.  We chose to break
  compositionality here because we think simple @('loop$')s are most common and
  wanted to keep their semantics simple.  I.e., we compromised.</p>

  <p>By the way, if you want the prover to convert every simple scion to its
  fancy counterpart you could prove rewrite rules like that below.</p>

  @({
  (defthm convert-collect$-to-collect$+
    (implies (ok-fnp fn)
             (equal (collect$ fn lst)
                    (collect$+ `(lambda (loop$-gvars loop$-ivars)
                                  (,fn (car loop$-ivars)))
                               nil
                               (loop$-as (list lst)))))
    :hints (("[1]Goal"
             :expand ((tamep (cons fn '(x)))
                      (tamep (cons fn '((car loop$-ivars))))))))
  })")

(defxdoc forall
  :parents (defun-sk)
  :short "Universal quantifier"
  :long "<p>The symbol @('forall') (in the ACL2 package) represents universal
 quantification in the context of a @(tsee defun-sk) form.  See @(see defun-sk)
 and see @(see exists).</p>

 <p>See @(see quantifiers) for an example illustrating how the use of
 recursion, rather than explicit quantification with @(tsee defun-sk), may be
 preferable.</p>")

(defxdoc force
  :parents (rewrite linear type-prescription definition meta)
  :short "Identity function used to force a hypothesis"
  :long "<p>@('Force') is the identity function: @('(force x)') is equal to
 @('x').  However, for rules of many classes (see @(see rule-classes)), a
 hypothesis of the form @('(force term)') is given special treatment, as
 described below.  This treatment takes place for rule classes @(':')@(tsee
 rewrite), @(':')@(tsee linear), @(':')@(tsee type-prescription), @(':')@(tsee
 definition), @(':')@(tsee meta) (actually in that case, the result of
 evaluating the hypothesis metafunction call), and @(':')@(tsee
 forward-chaining).</p>

 <p>When a hypothesis of a conditional rule (of one of the classes listed
 above) has the form @('(force hyp)'), it is logically equivalent to @('hyp')
 but has a pragmatic effect.  In particular, when the rule is considered, the
 needed instance of the hypothesis, @('hyp''), may be assumed if the usual
 process fails to prove it or its negation.  In that situation, if the rule is
 eventually applied, then a special case is generated, requiring the system to
 prove that @('hyp'') is true in the current context.  The proofs of all such
 ``forced assumptions'' are, by default, delayed until the successful
 completion of the main goal.  See @(see forcing-round) and see @(see
 immediate-force-modep).</p>

 <p>Note that the only time that ACL2 gives special treatment to calls of
 @('force') is when it is considering the hypotheses of a conditional rule, as
 discussed above.  In particular, when the rewriter encounters a subterm of the
 goal currently being simplified, a call of @('force') is not treated
 specially.  For example, if you provide a @(':use') hint (see @(see hints))
 that replaces a goal @('G') by the goal</p>

 @({
 (implies (implies (and ... (force HYP) ...)
                   concl)
          G)
 })

 <p>then the rewriter will not give any special treatment to <tt>(force
 HYP)</tt>.  Instead, it will first rewrite @('HYP') to, say, @('HYP''); and
 then, using the fact that @('force') is the identity function, the rewriter
 will return @('HYP'') as the rewritten value for <tt>(force HYP)</tt>.</p>

 <p>Forcing is generally used on hypotheses that are always expected to be
 true, as is commonly the case for @(see guard)s of functions.  All the power
 of the theorem prover is brought to bear on a forced hypothesis and no
 backtracking is possible.  Forced goals can be attacked immediately (see @(see
 immediate-force-modep)) or in a subsequent forcing round (see @(see
 forcing-round)).  Also see @(see case-split) for a related utility.  If the
 @(':')@(tsee executable-counterpart) of the function @('force') is @(see
 disable)d, then no hypothesis is forced.  For more on enabling and disabling
 forcing, see @(see enable-forcing) and see @(see disable-forcing).</p>

 <p>It sometimes happens that a conditional rule is not applied because some
 hypothesis, @('hyp'), could not be relieved, even though the required instance
 of @('hyp'), @('hyp''), can be shown true in the context.  This happens when
 insufficient resources are brought to bear on @('hyp'') at the time we try to
 relieve it.  A sometimes desirable alternative behavior is for the system to
 assume @('hyp''), apply the rule, and to generate explicitly a special case to
 show that @('hyp'') is true in the context.  This is called ``forcing''
 @('hyp').  It can be arranged by restating the rule so that the offending
 hypothesis, @('hyp'), is embedded in a call of @('force'), as in @('(force
 hyp)').  By using the @(':')@(tsee corollary) field of the @(tsee
 rule-classes) entry, a hypothesis can be forced without changing the statement
 of the theorem from which the rule is derived.</p>

 <p>Technically, @('force') is just a function of one argument that returns
 that argument.  It is generally @(see enable)d and hence evaporates during
 simplification.  But its presence among the hypotheses of a conditional rule
 causes case splitting to occur if the hypothesis cannot be conventionally
 relieved.</p>

 <p>Since a forced hypothesis must be provable whenever the rule is otherwise
 applicable, forcing should be used only on hypotheses that are expected always
 to be true.</p>

 <p>A particularly common situation in which some hypotheses should be forced
 is in ``most general'' @(see type-prescription) lemmas.  If a single lemma
 describes the ``expected'' type of a function, for all ``expected'' arguments,
 then it is probably a good idea to force the hypotheses of the lemma.  Thus,
 every time a term involving the function arises, the term will be given the
 expected type and its arguments will be required to be of the expected type.
 In applying this advice it might be wise to avoid forcing those hypotheses
 that are in fact just type predicates on the arguments, since the application
 of @(see type-prescription) lemmas generally has fairly thorough knowledge of
 the types of all terms (see @(see type-prescription) for relevant
 background).</p>

 <p>@('Force') can have the additional benefit of causing the ACL2 typing
 mechanism to interact with the ACL2 rewriter to establish the hypotheses of
 @(see type-prescription) rules.  See @(see type-reasoning) for relevant
 background for the following explanation.  If type reasoning alone is
 insufficient to prove some instance of a hypothesis, then the instance will
 not be proved by type reasoning and a @(see type-prescription) rule with that
 hypothesis will be inapplicable in that case.  But by embedding such
 hypotheses in @('force') expressions you can effectively cause the type system
 to ``punt'' them to the rest of the theorem prover.  Of course, as already
 noted, this should only be done on hypotheses that are ``always true.''  In
 particular, if rewriting is required to establish some hypothesis of a @(see
 type-prescription) rule, then the rule will be found inapplicable because the
 hypothesis will not be established by type reasoning alone.</p>

 <p>The ACL2 rewriter uses the type reasoning system as a subsystem.  It is
 therefore possible that the type system will force a hypothesis that the
 rewriter could establish.  Before a forced hypothesis is reported out of the
 rewriter, we try to establish it by rewriting.</p>

 <p>This makes the following surprising behavior possible: A @(see
 type-prescription) rule fails to apply because some true hypothesis is not
 being relieved.  The user changes the rule so as to <b>force</b> the
 hypothesis.  The system then applies the rule but reports no forcing.  How can
 this happen?  The type system ``punted'' the forced hypothesis to the
 rewriter, which established it.</p>

 <p>The discussion above may give the impression that a forcing round only
 takes place because of a failure to relieve a forced hypothesis.  A notable
 exception, however, is due to @(see linear-arithmetic).  Consider the
 following example:</p>

 @({
 (implies (not (equal 0 x))
          (or (< 0 x) (< x 0)))
 })

 <p>This is not a theorem; in particular, it fails when @('x') is @('nil').
 What is missing is the hypothesis, @('(acl2-numberp x)').  If you try to prove
 the displayed formula above and you look at the proof using @(':')@(tsee pso),
 you'll see the following.</p>

 @({
 But forced simplification reduces this to T, using the :executable-
 counterpart of FORCE and linear arithmetic.
 })

 <p>Thus, no specific rule created this forcing round (see also @(see
 forcing-round)).  Rather, ACL2 was able to prove the goal using linear
 arithmetic, but it needed to force the assumption that @('x') is a number.
 This is clear when we look at output for the forcing round:</p>

 @({
 [1]Goal, below, will focus on
 (ACL2-NUMBERP X),
 which was forced in
  Goal'
   by the linearization of
   (EQUAL 0 X).
 })

 <p>Finally, we should mention that the rewriter is never willing to force when
 there is an @(tsee if) term present in the goal being simplified.  Since
 @(tsee and) terms and @(tsee or) terms are merely abbreviations for @(tsee if)
 terms, they also prevent forcing.  Note that @(tsee if) terms are ultimately
 eliminated using the ordinary flow of the proof (but see @(see
 set-case-split-limitations)), allowing @('force') ultimately to function as
 intended.  Moreover, forcing can be disabled, as described above; also see
 @(see disable-forcing).</p>

 @(def force)")

(defxdoc forcing-round
  :parents (force)
  :short "A section of a proof dealing with @(see force)d assumptions"
  :long "<p>If ACL2 ``@(see force)s'' some hypothesis of some rule to be true,
 it is obliged later to prove the hypothesis.  See @(see force).  ACL2 delays
 the consideration of @(see force)d hypotheses until the main goal has been
 proved.  It then undertakes a new round of proofs in which the main goal is
 essentially the conjunction of all hypotheses @(see force)d in the preceding
 proof.  Call this round of proofs the ``Forcing Round.''  Additional
 hypotheses may be @(see force)d by the proofs in the Forcing Round.  The
 attempt to prove these hypotheses is delayed until the Forcing Round has been
 successfully completed.  Then a new Forcing Round is undertaken to prove the
 recently @(see force)d hypotheses and this continues until no hypotheses are
 @(see force)d.  Thus, there is a succession of Forcing Rounds.</p>

 <p>The Forcing Rounds are enumerated starting from 1.  The Goals and Subgoals
 of a Forcing Round are printed with the round's number displayed in square
 brackets.  Thus, @('"[1]Subgoal 1.3"') means that the goal in question is
 Subgoal 1.3 of the 1st forcing round.  To supply a hint for use in the proof
 of that subgoal, you should use the goal specifier @('"[1]Subgoal 1.3"').
 See @(see goal-spec).</p>

 <p>When a round is successfully completed &mdash; and for these purposes you
 may think of the proof of the main goal as being the 0th forcing round &mdash;
 the system collects all of the assumptions @(see force)d by the just-completed
 round.  Here, an assumption should be thought of as an implication,
 @('(implies context hyp)'), where context describes the context in which hyp
 was assumed true.  Before undertaking the proofs of these assumptions, we try
 to ``clean them up'' in an effort to reduce the amount of work required.  This
 is often possible because the @(see force)d assumptions are generated by the
 same rule being applied repeatedly in a given context.</p>

 <p>By delaying and collecting the @('forced') assumptions until the completion
 of the ``main goal'' we gain two advantages.  First, the user gets
 confirmation that the ``gist'' of the proof is complete and that all that
 remains are ``technical details.''  Second, by delaying the proofs of the
 @(see force)d assumptions ACL2 can undertake the proof of each assumption only
 once, no matter how many times it was @(see force)d in the main goal.</p>

 <p>In order to indicate which proof steps of the previous round were
 responsible for which @(see force)d assumptions, we print a sentence
 explaining the origins of each newly @(see force)d goal.  For example,</p>

 @({
  [1]Subgoal 1, below, will focus on
  (GOOD-INPUTP (XTRANS I)),
  which was forced in
   Subgoal 14, above,
    by applying (:REWRITE PRED-CRUNCHER) to
    (PRED (XTRANS I) I),
   and
   Subgoal 28, above,
    by applying (:REWRITE PRED-CRUNCHER) to
    (PRED (XTRANS I) I).
 })

 <p>In this entry, ``[1]Subgoal 1'' is the name of a goal which will be proved
 in the next forcing round.  On the next line we display the @(see force)d
 hypothesis, call it @('x'), which is @('(good-inputp (xtrans i))') in this
 example.  This term will be the conclusion of the new subgoal.  Since the new
 subgoal will be printed in its entirety when its proof is undertaken, we do
 not here exhibit the context in which @('x') was @(see force)d.  The sentence
 then lists (possibly a succession of) a goal name from the just-completed
 round and some step in the proof of that goal that @(see force)d @('x').  In
 the example above we see that Subgoals 14 and 28 of the just-completed proof
 @(see force)d @('(good-inputp (xtrans i))') by applying @('(:rewrite
 pred-cruncher)') to the term @('(pred (xtrans i) i)').</p>

 <p>If one were to inspect the theorem prover's description of the proof steps
 applied to Subgoals 14 and 28 one would find the word ``@(see force)d'' (or
 sometimes ``forcibly'') occurring in the commentary.  Whenever you see that
 word in the output, you know you will get a subsequent forcing round to deal
 with the hypotheses @(see force)d.  Similarly, if at the beginning of a
 forcing round a @(see rune) is blamed for causing a @(see force) in some
 subgoal, inspection of the commentary for that subgoal will reveal the word
 ``@(see force)d'' after the rule name blamed.</p>

 <p>Most @(see force)d hypotheses come from within the prover's simplifier.
 When the simplifier encounters a hypothesis of the form @('(force hyp)') it
 first attempts to establish it by rewriting @('hyp') to, say, @('hyp'').  If
 the truth or falsity of @('hyp'') is known, forcing is not required.
 Otherwise, the simplifier actually @(see force)s @('hyp'').  That is, the
 @('x') mentioned above is @('hyp''), not @('hyp'), when the @(see force)d
 subgoal was generated by the simplifier.</p>

 <p>Once the system has printed out the origins of the newly @(see force)d
 goals, it proceeds to the next forcing round, where those goals are
 individually displayed and attacked.</p>

 <p>At the beginning of a forcing round, the @(see enable)d structure defaults
 to the global @(see enable)d structure.  For example, suppose some @(see
 rune), @('rune'), is globally @(see enable)d.  Suppose in some event you @(see
 disable) the @(see rune) at @('"Goal"') and successfully prove the goal but
 @(see force) @('"[1]Goal"').  Then during the proof of @('"[1]Goal"'),
 @(see rune) is @(see enable)d ``again.''  The right way to think about this is
 that the @(see rune) is ``still'' @(see enable)d.  That is, it is @(see
 enable)d globally and each forcing round resumes with the global @(see
 enable)d structure.</p>")

(defxdoc formula
  :parents (history world acl2-built-ins)
  :short "The formula of a name or @(see rune)"
  :long "<p>The ACL2 system function, @('formula'), returns the @(see term)
 associated with a given @(see rune) or symbolic name, returning @('nil') if
 there is no such term.  Note that a non-@('nil') result will be an ACL2
 ``translated'' term (see @(see term)).  Most ACL2 users probably will have no
 reason to know about this function.  But here we document this function for
 those who write system-level tools, since they might find this interface to
 the ACL2 logical @(see world) to be useful.</p>

 <p>When ACL2 is given a @(':use') or @(':by') hint, it looks for the @(see
 term) stored in the ACL2 logical @(see world) that is associated with the name
 given in the hint, which is a symbol or a @(see rune).  (See @(see
 lemma-instance).)  The utility used to find that term is @('formula'), which
 ACL2 invokes as follows.</p>

 @({
 (formula x t wrld)   ; for :use hints
 (formula x nil wrld) ; for :by hints
 })

 <p>The second argument can affect whether or not to use a normalized version
 of the term (in particular, a definition body) associated with @('x'); see
 @(see normalize).  The value is @('t') for @(':use') @(see hints) because
 normalizing a term simplifies it, which is often desirable.  But for a
 @(':by') hint, the non-normalized version of the term is used in order to
 increase the chance that the necessary subsumption test will succeed.  Even if
 the second argument is @('t'), normalization might not take place.  In the
 unlikely case that you need to know more precisely the effect of supplying
 @('t'), see the source code for @('formula').</p>

 <p>Here are some examples.  Note that @('(w state)') returns the current ACL2
 logical @(see world).  First let us submit a few @(see events).</p>

 @({
 (defun f1 (x) (cons 3 x))
 (defun f2 (x y) (implies x y))
 (defthm one-rule
   (and (equal (* 2 y) (+ y y))
        (equal (* 3 y) (+ y y y))))
 (defthm two-rules
   t
   :rule-classes ((:rewrite :corollary (equal (* 2 y) (+ y y)))
                  (:rewrite :corollary (equal (* 3 y) (+ y y y)))))
 })

 <p>Then:</p>

 @({
 ACL2 !>(formula 'f1 nil (w state))
 (EQUAL (F1 X) (CONS '3 X))
 ACL2 !>(formula 'f1 t (w state))
 (EQUAL (F1 X) (CONS '3 X))
 ACL2 !>(formula 'f2 nil (w state))
 (EQUAL (F2 X Y) (IMPLIES X Y))
 ACL2 !>(formula 'f2 t (w state))
 (EQUAL (F2 X Y)
        (IF X (IF Y 'T 'NIL) 'T))
 ACL2 !>(formula 'one-rule nil (w state))
 (IF (EQUAL (BINARY-* '2 Y) (BINARY-+ Y Y))
     (EQUAL (BINARY-* '3 Y)
            (BINARY-+ Y (BINARY-+ Y Y)))
     'NIL)
 ACL2 !>(equal (formula 'one-rule nil (w state)) (formula 'one-rule t (w state)))
 T
 ACL2 !>(formula 'two-rules nil (w state))
 'T
 ACL2 !>(formula 'two-rules t (w state))
 'T
 ACL2 !>(formula '(:rewrite two-rules . 1) nil (w state))
 (EQUAL (BINARY-* '2 Y) (BINARY-+ Y Y))
 ACL2 !>(formula '(:rewrite two-rules . 2) nil (w state))
 (EQUAL (BINARY-* '3 Y)
        (BINARY-+ Y (BINARY-+ Y Y)))
 ACL2 !>(formula 'no-such-rule nil (w state))
 NIL
 ACL2 !>
 })")

(defxdoc forward-chaining
  :parents (rule-classes)
  :short "Make a rule to forward chain when a certain trigger arises"
  :long "<p>See @(see rule-classes) for a general discussion of rule classes,
 including how they are used to build rules from formulas and a discussion of
 the various keywords in a rule class description.</p>

 @({
  Examples:

  (defthm p-and-r-forward           ; When (p a) appears in a formula to be
   (implies (and (p x) (r x))       ; simplified, try to establish (p a) and
            (q (f x)))              ; (r a) and, if successful, add (q (f a))
   :rule-classes :forward-chaining) ; to the known assumptions.

  (defthm p-and-r-forward           ; as above with most defaults filled in
    (implies (and (p x) (r x))
             (q (f x)))
    :rule-classes ((:forward-chaining :trigger-terms ((p x))
                                      :corollary (implies (and (p x) (r x))
                                                          (q (f x)))
                                      :match-free :all)))
 })

 <p>To specify the triggering terms provide a non-empty list of terms as the
 value of the @(':trigger-terms') field of the rule class object.</p>

 @({
  General Form:
  Any theorem, provided an acceptable triggering term exists.
 })

 <p>The structure of this documentation is as follows.  First we give a brief
 overview of forward chaining and contrast it to backchaining (rewriting).
 Then we lay out the syntactic restrictions on @(':forward-chaining') rules.
 Then we give more details about the process and point to a tool to assist you
 in debugging your @(':forward-chaining') rules.</p>

 <p><i>Overview and When to Use Forward Chaining</i></p>

 <p>Forward chaining is performed as part of the simplification process: before
 the goal is rewritten a <i>context</i> is established.  The context tells the
 theorem prover what may be assumed during rewriting, in particular, to
 establish hypotheses of rewrite rules.  Forward chaining is used to extend the
 context before rewriting begins.  For example, the @(':forward-chaining') rule
 @('(implies (p x) (p1 x))') would add @('(p1 A)') to the context, where @('A')
 is some term, if @('(p A)') is already in the context.</p>

 <p>Forward chaining and backchaining are duals.  If a rewrite rule requires
 that @('(p1 A)') be established and @('(p A)') is known, it could be done
 either by making @('(implies (p x) (p1 x))') a @(':forward-chaining') rule or
 a @(':rewrite') rule.  Which should you choose?</p>

 <p>As a rule of thumb, if a conclusion like @('(p1 A)') is expected to be
 widely needed, it is better to derive it via forward chaining because then it
 is available ``for free'' during the rewriting after paying the one-time cost
 of forward chaining.  Alternatively, if @('(p1 A)') is a rather special
 hypothesis of key importance to only a few rewrite rules, it is best to derive
 it only when needed through backchaining.  Thus forward chaining is pro-active
 and backward chaining (rewriting) is reactive.</p>

 <p>The following example illustrates that forward chaining may be
 indispensable in a scenario with @(see free-variables), whose handling is
 quite weak with rewrite rules.</p>

 @({
 (defstub p0 (x) t)
 (defstub p1 (x) t)
 (defstub p2 (y) t)
 (defaxiom p0-implies-p1
   (implies (p0 x)
            (p1 x))
   :rule-classes :forward-chaining)
 (defaxiom p1-implies-p2
   (implies (p1 x)
            (p2 y)))
 ; ACL2 proves the following, but only because p0-implies-p1 is a
 ; :forward-chaining rule.  If p0-implies-p1 is instead a :rewrite
 ; rule, then the proof fails for the following event.
 (thm (implies (p0 x)
               (p2 y)))
 })

 <p><i>Syntactic Restrictions</i></p>

 <p>Forward chaining rules are generated from the corollary term (see @(see
 rule-classes)) as follows.  First, every @(tsee let) expression is expanded
 away (hence, so is every @(tsee let*) and @(tsee lambda) expression), and
 trivial ``guard holders'' are removed; see @(see guard-holders).  If the
 resulting term has the form @('(implies hyp concl)'), then @('concl') is
 treated as a conjunction, with one forward chaining rule with hypothesis
 @('hyp') created for each conjunct.  In the other case, where the corollary
 term is not an @(tsee implies), we process it as we process the conclusion in
 the first case.</p>

 <p>Note that unlike rewrite rules, a nested implication is not folded into a
 single implication.  Consider for example the following term.</p>

 @({
  (implies (p1 x)
           (implies (p2 x)
                    (p3 x)))
 })

 <p>Although this term is parsed for a rewrite rule as @('(implies (and (p1 x)
 (p2 x)) (p3 x))'), that is not the case when this term is parsed for a
 forward-chaining rule, in which case @('(p1 x)') is treated as the hypothesis
 and @('(implies (p2 x) (p3 x))') is treated as the conclusion.</p>

 <p>The @(':trigger-terms') field of a @(':forward-chaining') rule class object
 should be a non-empty list of terms, if provided, and should have certain
 properties described below.  If the @(':trigger-terms') field is not provided,
 it defaults to the singleton list containing the ``atom'' of the first
 hypothesis of the formula.  (The atom of @('(not x)') is @('x'); the atom of
 any other term is the term itself.)  If there are no hypotheses and no
 @(':trigger-terms') were provided, an error is caused.</p>

 <p>A triggering term is acceptable if it is not a variable, a quoted constant,
 a lambda application, a @(tsee let)- (or @(tsee let*)-) expression, or a
 @(tsee not)-expression, and every variable symbol in the conclusion of the
 theorem either occurs in the hypotheses or occurs in the trigger.</p>

 <p><i>More Details about Forward Chaining</i></p>

 <p>@(':Forward-chaining') rules are used by the simplifier <i>before</i> it
 begins to rewrite the literals of the goal.  (Forward chaining is thus carried
 out from scratch for each goal.)  If any term in the goal is an instance of a
 trigger of some forward chaining rule, we try to establish the hypotheses of
 that forward chaining theorem (from the negation of the goal).  To relieve a
 hypothesis we only use <see topic='@(url type-reasoning)'>type
 reasoning</see>, evaluation of ground terms, and presence among our known
 assumptions.  We do not use rewriting.  So-called free variables in hypotheses
 are treated specially; see @(see free-variables).  If all hypotheses are
 relieved, and certain heuristics approve of the newly derived conclusion, we
 add the instantiated conclusion to our known assumptions.  Since this might
 introduce new terms into the assumptions, forward chaining is repeated.
 Heuristic approval of each new addition is necessary to avoid infinite looping
 as would happen with the rule @('(implies
 (p x) (p (f x)))'), which might otherwise forward chain from @('(p A)') to
 @('(p (f A))') to @('(p (f (f A)))'), etc.</p>

 <p><i>Caution</i>.  Forward chaining does not actually add terms to the goals
 displayed during proof attempts.  Instead, it extends an associated
 <i>context</i>, called ``assumptions'' in the preceding paragraph, that ACL2
 builds from the goal currently being proved.  (For insiders: forward chaining
 extends the @(tsee type-alist).)  The context starts out with ``obvious''
 consequences of the negation of the goal.  For example, if the goal is</p>

 @({
  (implies (and (p A) (q (f A)))
           (c A))
 })

 <p>then the context notes that @('(p A)') and @('(q (f A))') are non-@('nil')
 and @('(c A)') is @('nil').  Forward chaining is then used to expand the
 context.  For example, if a forward chaining rule has @('(f x)') as a trigger
 term and has body @('(implies (p x) (r (f x)))'), then the context is extended
 by binding @('(r (f A))') to non-@('nil'), provided the heuristics approve of
 this extension.  Note however that since @('(r (f A))') is put into the
 context, not the goal, you will not see it in the goal formula.  Furthermore,
 the assumption added to the context is just the instantiation of the
 conclusion of the rule, with no simplification or rewriting applied.  Thus,
 for example, if it contains an enabled non-recursive function symbol it is
 unlikely ever to match a (rewritten) term arising during subsequent
 simplification of the goal.</p>

 <p>However, forward-chaining does support the linear arithmetic reasoning
 package.  For example, suppose that forward-chaining puts @('(< (f x) (g x))')
 into the context.  Then this inequality also goes into the linear arithmetic
 database, together with suitable instances of linear lemmas whose trigger term
 is a call of @('g').  See @(see linear).</p>

 <p>Debugging @(':forward-chaining') rules can be difficult since their effects
 are not directly visible on the goal being simplified.  Tools are available to
 help you discover what forward chaining has occurred see @(see
 forward-chaining-reports).</p>")

(defxdoc forward-chaining-reports
  :parents (forward-chaining debugging)
  :short "To see reports about the forward chaining process"
  :long "<p>Debugging forward-chaining rules can be hard because their effects
 are not directly visible on the goal.  In this documentation we tell you how
 to get reports on the forward chaining activity occurring in your proof
 attempts.  This documentation is written in several parts.  The first part is
 an introduction for the first-time user of forward chaining reports.  The next
 two parts describe how to read reports.  The last part describes how to
 monitor forward chaining activity only for selected runes, etc.  We recommend
 the new user of these reports read everything!</p>

 <p><i>A Quick Introduction to Forward Chaining Reports</i></p>

 <p>Caution: The reporting mechanism maintains some state, and if you have
 already used forward chaining reporting in a session, the directions below may
 not work as advertised!  To return to the default forward chaining reporting
 state, execute this form at the top level:</p>

 @({
  (reset-fc-reporting)
 })

 <p>You can get a report about all forward chaining activity in subsequent
 proofs by doing:</p>

 @({
  (set-fc-criteria t)
 })

 <p>Options will be discussed later that allow you to monitor the activity
 caused by particular @(':forward-chaining') rules or terms.</p>

 <p>Then do a proof that is expected to cause some forward chaining.  In the
 proof output you will see lines like this:</p>

 @({
  (Forward Chaining on behalf of PREPROCESS-CLAUSE:  (FC-Report 1))
 })

 <p>This is the only difference you should see in the proof output.</p>

 <p>After the proof attempt has terminated, you can execute:</p>

 @({
  (fc-report k)
 })

 <p>for any @('k') printed during the immediately preceding proof attempt.
 That will print a much longer report describing the activity that occurred
 during the @('k')th use of forward chaining in that proof attempt.</p>

 <p>If you want to see these reports in real time (embedded in the proof
 output), do this before invoking the prover:</p>

 @({
  (set-fc-report-on-the-fly t)
 })

 <p>Collecting the data used to generate these reports slows down the prover.
 If you no longer wish to see such reports, do</p>

 @({
  (set-fc-criteria nil)
 })

 <p><i>How To Read FC Reports</i></p>

 <p>The report printed by @('(fc-report k)') is of the form:</p>

 <code>
  Forward Chaining Report <i>k</i>:
  Caller: <i>token</i>
  Clause: (<i>lit1</i> <i>lit2</i> ... <i>litn</i>)
  Number of Rounds: <i>m</i>
  Contradictionp: <i>bool</i>
  Activations: (<i>act1</i> <i>act2</i> ...)
  </code>

 <p>This report means that the <i>k</i>th use of forward chaining in the most
 recent proof attempt was done on behalf of <i>token</i> (see below).  The
 initial context (set of assumptions) consisted of the negations of the
 literals listed in the @(see clause) shown and the initial candidate trigger
 terms are all those appearing in that clause.  This invocation of forward
 chaining proceeded to do <i>m</i> rounds of successive extensions of the
 initial context and ultimately either reached a contradiction (<i>bool</i> =
 @('T')) or returned an extended context (<i>bool</i> = @('NIL')).  Note that
 reaching a contradiction from the negations of all the literals in a clause is
 ``good'' because it means the clause is true.  The report concludes with the
 final status of all the forward chaining rules fired during the process.  We
 explain how to read one of these activation reports in the next section.</p>

 <p>Forward chaining is done on behalf of many proof techniques in the system.
 Each is associated with a <i>token</i>.  The main proof technique that uses
 forward chaining is @('SIMPLIFY-CLAUSE').  This is the call of forward
 chaining that sets up the context used by the rewriter to relieve hypotheses
 during backchaining.  Another common caller of forward chaining is
 @('PREPROCESS-CLAUSE'), the first process in the ACL2 waterfall (see @(see
 hints-and-the-waterfall)).  Forward chaining often proves ``near
 propositional'' goals (those depending just on boolean implications between
 basic predicates).  Other tokens you may see include @('INDUCT'), which uses
 forward chaining to set up a context for applying @(':')@(tsee induction)
 rules, and the definitional principle (and related utilities such as @(tsee
 verify-termination) and @(tsee verify-guards)) which uses forward chaining
 during the construction of both measure conjectures and guard conjectures.
 When used this way, the <i>token</i> is @('defun-or-guard-verification').</p>

 <p><i>How to Read Activation Reports</i></p>

 <p>The forward chaining report concludes with a list of activation
 reports.</p>

 <code>
 Activations: (<i>act1</i> <i>act2</i> ...)
 </code>

 <p>Each <i>acti</i> is of the form:</p>

 <code>
 (<i>rune</i>
  (:TRIGGER <i>inst-trig</i>)
  ((:UNIFY-SUBST <i>subst</i>)
   (:DISPOSITION <i>outcome-part1</i> <i>outcome-part2</i> <i>inst-term</i>))
  ...)
 </code>

 <p>where the @('...') indicates that the rest of the report consists of more
 of those tuples listing a @(':UNIFY-SUBST') and @(':DISPOSITION').  We call
 each tuple a <i>disposition</i> of the activation and each disposition
 describes a substitution <i>subst</i> identifying the final instantiation of
 the rule and how the activation fared.  Suppose there are <i>n</i>
 dispositions.  (If the rule in question contains no free variables, <i>n</i>
 will be 1.)</p>

 <p>This activation report means that during the forward chaining process in
 question, the @(':')@(tsee forward-chaining) @(see rune) <i>rune</i> was fired
 due to the presence in the evolving context of the trigger term
 <i>inst-trig</i>.  (Note that <i>inst-trig</i> is an instantiation of the
 trigger term of the named rule.  That is, the variable symbols you see in
 <i>inst-trig</i> are those of the clause printed in the forward chaining
 report.)  The activation of <i>rune</i> by <i>inst-trig</i> proceeded to split
 <i>n</i> ways as different choices were made for the @(see free-variables)
 occurring among the hypotheses.  Each of those <i>n</i> choices gave rise to a
 different substitution <i>subst</i>, and each succeeded or failed as described
 by the corresponding @(':DISPOSITION').</p>

 <p>The @(':DISPOSITION') of an activation is described in three parts,
 <i>outcome-part1</i>, <i>outcome-part2</i>, and <i>inst-term</i>.
 <i>Outcome-part1</i> is either @('SUCCESS') or @('BLOCKED'), meaning that the
 instance given by <i>subst</i> either succeeded in the sense that all of its
 instantiated hypotheses were found in the context, or failed because some
 instantiated hypothesis was not found.</p>

 <p>If @('outcome-part1') is @('SUCCESS') then <i>inst-term</i> is the
 instantiated conclusion produced by the rule.  <i>Outcome-part2</i> is
 @('APPROVED') if the instantiated conclusion was acceptable to our heuristics
 designed to prevent looping and not already known in the evolving context.
 <i>Outcome-part2</i> is @('REJECTED') if the instantiated conclusion was not
 approved by our heuristics.  <i>Outcome-part2</i> is @('REDUNDANT') if the
 instantiated conclusion was approved by the heuristics but already known true
 in the current evolving context.  If @('APPROVED'), the truth of the
 instantiated conclusion is added to the evolving context.  Otherwise, it is
 not.</p>

 <p>If @('outcome-part1') is @('BLOCKED') then @('outcome-part2') is one of
 three possible things: @('FALSE'), in which case <i>inst-term</i> is an
 instantiated hypothesis of the rule that is assumed false in the current
 context, @('UNRELIEVED-HYP'), in which case <i>inst-term</i> is an
 instantiated hypothesis whose truth value is not determined by the context, or
 @('UNRELIEVED-HYP-FREE'), in which case <i>inst-term</i> is an oddly
 instantiated hypothesis whose truth value is not determined by the context and
 which also contains free variables.  In the last case, the ``odd''
 instantiation was by the substitution <i>subst</i> but extended so that free
 variables in the hypothesis are renamed to start with the prefix
 @('UNBOUND-FREE-') to draw your attention to them.</p>

 <p>Note: All of the terms printed in the report are instantiated with the
 relevant unifying substitution (possibly extended to bind free variables).</p>

 <p><i>Specifying the Tracking Criteria</i></p>

 <p>During a proof attempt, the forward chaining module stores information
 about the activations satisfying certain criteria.  The <i>criteria</i> is a
 list of triples.  Each triple consists of a forward chaining rune, an
 instantiated trigger term, and an instantiated conclusion to watch for.
 However, any or all of the components of such a triple may be @('t') and that
 is given special significance.</p>

 <p>An activation @('satisfies') a criteria if it satisfies at least one of the
 triples.  An activation satisfies a triple if it satisfies all three of the
 components.  Every activation satisfies the component @('t').  An activation
 satisfies a rune if the activation describes a firing of the named rule.  An
 activation satisfies an instantiated trigger term if the activation was
 created by that trigger being present in the context.  An activation satisfies
 an instantiated conclusion if the activation <i>could</i> produce the
 instantiated conclusion (with the right choice of any free variables).</p>

 <p>Thus, the criteria is interpreted as a disjunction of conjunctions, making
 it possible to track a specific set of runes, triggers, and conclusions.</p>

 <p>For example, here is a triple that might appear in the criteria:</p>

 @({
  ((:FORWARD-CHAINING ALISTP-FORWARD-TO-TRUE-LISTP)
   t
   t).
 })

 <p>This triple would cause every activation of the given rule to be tracked.
 However, the triple</p>

 @({
  ((:FORWARD-CHAINING ALISTP-FORWARD-TO-TRUE-LISTP)
   (ALISTP (MAKE-BINDINGS VARS (TOP-N (OP1 INST) (STACK S))))
   t)
 })

 <p>would only track activations of that rule fired by the specific term shown
 as the second element of the triple.  Furthermore</p>

 @({
  (t
   (ALISTP (MAKE-BINDINGS VARS (TOP-N (OP1 INST) (STACK S))))
   t)
 })

 <p>would track any forward chaining rule triggered by that term, and</p>

 @({
  (t
   t
   (TRUE-LISTP (MAKE-BINDINGS VARS (TOP-N (OP1 INST) (STACK S)))))
 })

 <p>would track any rule fired by any trigger that might lead to the specific
 term given as the third component above.</p>

 <p>Note: The condition on how an activation satisfies an instantiated
 conclusion is a little subtle.  Consider the activation of the forward
 chaining rule</p>

 @({
  (implies (and (symbol-listp x)
                (equal (len x) (len y)))
           (true-listp (make-bindings x y)))
 })

 <p>triggered by @('(SYMBOL-LISTP VARS)') arising in the current context.  This
 activation <i>could</i> produce the specific conclusion shown in the last
 triple above, if it just happened that @('(TOP-N (OP1 INST) (STACK S))') were
 chosen as the binding of the free variable @('y').  Thus, the activation of
 this rule triggered by @('(SYMBOL-LISTP VARS)') satisfies the last triple
 above.</p>

 <p>Observe that the triple</p>

 @({
  (t t t)
 })

 <p>is satisfied by every activation of any rule by any trigger term producing
 any conclusion.</p>

 <p>The function @('set-fc-criteria') sets the criteria describing which
 activations are to be tracked.  For example, if you execute:</p>

 @({
  (set-fc-criteria ((:FORWARD-CHAINING LEMMA1)
                    t t)
                   ((:FORWARD-CHAINING LEMMA2)
                    (ALISTP (BASIC-MAPPER A B))
                    t)
                   (t t (TRUE-LISTP (DLT D)))),
 })

 <p>the system would track all activations of the forward-chaining rule
 @('LEMMA1'), plus those activations of forward-chaining rule @('LEMMA2')
 triggered by the term given in the second triple, plus any activation of any
 rule that might derive @('(TRUE-LISTP (DLT D))').</p>

 <p>Because criteria generally mention variable symbols used in a specific
 conjecture, it is probably best to reconsider your criteria every time you
 want to track forward chaining.</p>

 <p>If the criteria is @('nil'), then nothing is tracked.  Setting the criteria
 to @('nil') is the way you turn off tracking and reporting of forward chaining
 activity.  You may do this either by @('(set-fc-criteria)') or by
 @('(set-fc-criteria nil)').  (Technically the second form is an odd use of
 @('set-fc-criteria'), which expects any supplied arguments to be triples; if
 the ``triple'' @('nil') is the only one supplied, we take it to mean that the
 entire criteria should be @('nil').)</p>

 <p>To track every forward chaining activation you may set the criteria with
 either @('(set-fc-criteria (t t t))') or use the abbreviation
 @('(set-fc-criteria t)').</p>

 <p>If, when you read a forward chaining report, you see no mention of an
 activation you have in mind, e.g., of a certain rune or deriving a certain
 conclusion, and you have set the criteria correctly, then the activation never
 happened.  (This is akin to using @(':')@(tsee brr) and @(':')@(tsee monitor)
 to monitor the application of a rewrite rule and then seeing no interactive
 break.)</p>

 <p>For some relevant functions to help you manage criteria and when the full
 reports are printed see @(tsee fc-report), @(tsee show-fc-criteria), @(tsee
 set-fc-criteria), @(tsee reset-fc-reporting), and @(tsee
 set-fc-report-on-the-fly).</p>")

(defxdoc fourth
  :parents (nth acl2-built-ins)
  :short "Fourth member of the list"
  :long "<p>See any Common Lisp documentation for details.</p>")

(defxdoc fp
  :parents (df)
  :short "Floating-point and ACL2"
  :long "<p>ACL2 supports computation that uses floating-point operations; see
 @(see df).  If you are using an older Lisp, an attempt to build ACL2 may fail
 with an error complaining that &ldquo;feature :ieee-floating-point is
 missing&rdquo; [from the Lisp's @('*features*')].  <b>THIS ERROR INDICATES
 THAT ACL2 MAY BE UNSOUND WHEN BUILT ON THAT LISP!</b> If however you believe
 that your Lisp properly supports IEEE floating-point operations even though
 that feature is missing (e.g., quite possibly with older versions of CCL), you
 can avoid that build-time error by setting environment variable
 @('ACL2_FP_OK') to any non-empty string.  You might want to do that in a
 script that invokes your Lisp.</p>")

(defxdoc free-variables
  :parents (rule-classes rewrite)
  :short "Free variables in rules"
  :long "<p>As described elsewhere (see @(see rule-classes)), ACL2 rules are
 treated as implications for which there are zero or more hypotheses @('hj') to
 prove.  In particular, rules of class @(':')@(tsee rewrite) may look like
 this:</p>

 @({
  (implies (and h1 ... hn)
           (fn lhs rhs))
 })

 <p>Variables of @('hi') are said to occur <i>free</i> in the above
 @(':rewrite') rule if they do not occur in @('lhs') or in any @('hj') with
 @('j<i').  (To be precise, here we are only discussing those variables that
 are not in the scope of a @(tsee let)/@(tsee let*)/@('lambda') that binds
 them.)  We also refer to these as the <i>free variables</i> of the rule.  ACL2
 may issue a warning or error when there are free variables in a rule, as
 described below.  (Variables of @('rhs') may be considered free if they do not
 occur in @('lhs') or in any @('hj').  But we do not consider those in this
 discussion.)</p>

 <p>In general, the <i>free variables</i> of rules are those variables
 occurring in their hypotheses (not @(tsee let)/@(tsee let*)/@('lambda')-bound)
 that are not bound when the rule is applied.  For rules of class @(':')@(tsee
 linear) and @(':')@(tsee forward-chaining), variables are bound by a trigger
 term.  (See @(see rule-classes) for a discussion of the @(':trigger-terms')
 field).  For rules of class @(':')@(tsee type-prescription), variables are
 bound by the @(':typed-term') field.</p>

 <p>See @(see free-variables-examples) for more examples of how this all works,
 including illustration of how the user can exercise some control over it.  In
 particular, see @(see free-variables-examples-rewrite) for an explanation of
 output from the @(see break-rewrite) facility in the presence of rewriting
 failures involving free variables, as well as an example exploring ``binding
 hypotheses'' as described below.</p>

 <p>Let us discuss the method for relieving hypotheses of @(see rewrite) rules
 with free variables.  Similar considerations apply to @(see linear) and @(see
 forward-chaining) rules, and @(see type-prescription) rules.  Note that the
 @(':match-free') mechanism discussed below does not apply to @(see
 type-prescription) rules.  See @(see free-variables-type-prescription) for a
 discussion of how to control free-variable matching for @(see
 type-prescription) rules.</p>

 <p>We begin with an example.  Does the proof of the @(tsee thm) below
 succeed?</p>

 @({
  (defstub p2 (x y) t)

  (defaxiom p2-trans
    (implies (and (p2 x y)
                  (p2 y z))
             (equal (p2 x z) t))
    :rule-classes ((:rewrite :match-free :all)))

  (thm (implies (and (p2 a c)
                     (p2 a b)
                     (p2 c d))
                (p2 a d)))
 })

 <p>Consider what happens when the proof of the @('thm') is attempted.  The
 ACL2 rewriter attempts to apply rule @('p2-trans') to the conclusion, @('(p2 a
 d)').  So, it binds variables @('x') and @('z') from the left-hand side of the
 conclusion of @('p2-trans') to terms @('a') and @('d'), respectively, and then
 attempts to relieve the hypotheses of @('p2-trans').  The first hypothesis of
 @('p2-trans'), @('(p2 x y)'), is considered first.  Variable @('y') is free in
 that hypothesis, i.e., it has not yet been bound.  Since @('x') is bound to
 @('a'), the rewriter looks through the context for a binding of @('y') such
 that @('(p2 a y)') is true, and it so happens that it first finds the term
 @('(p2 a b)'), thus binding @('y') to @('b').  Now it goes on to the next
 hypothesis, @('(p2 y z)').  At this point @('y') and @('z') have already been
 bound to @('b') and @('d'); but @('(p2 b d)') cannot be proved.</p>

 <p>So, in order for the proof of the @(tsee thm) to succeed, the rewriter
 needs to backtrack and look for another way to instantiate the first
 hypothesis of @('p2-trans').  Because @(':match-free :all') has been
 specified, backtracking does take place.  This time @('y') is bound to @('c'),
 and the subsequent instantiated hypothesis becomes @('(p2 c d)'), which is
 true.  The application of rule @('(p2-trans)') succeeds and the theorem is
 proved.</p>

 <p>If instead @(':match-free :all') had been replaced by @(':match-free
 :once') in rule @('p2-trans'), then backtracking would not occur, and the
 proof of the @(tsee thm) would fail.</p>

 <p>Next we describe in detail the steps used by the rewriter in dealing with
 free variables.</p>

 <p>The ACL2 rewriter uses the following sequence of steps to relieve a
 hypothesis with free variables, except that steps (1) and (3) are skipped for
 @(':forward-chaining') rules and step (3) is skipped for
 @(':type-prescription') rules.  First, if the hypothesis is of the form
 @('(force hyp0)') or @('(case-split hyp0)'), then replace it with
 @('hyp0').</p>

 <blockquote><p>(1) Suppose the hypothesis has the form @('(equiv var term)')
 where @('var') is free and no variable of @('term') is free, and either
 @('equiv') is @(tsee equal) or else @('equiv') is a known @(see equivalence)
 relation and @('term') is a call of @(tsee double-rewrite).  We call this a
 ``binding hypothesis.''  Then bind @('var') to the result of rewriting
 @('term') in the current context.</p>

 <p>(2) Look for a binding of the free variables of the hypothesis so that the
 corresponding instance of the hypothesis is known to be true in the current
 context.</p>

 <p>(3) Search all @(tsee enable)d, hypothesis-free rewrite rules of the form
 @('(equiv lhs rhs)'), where @('lhs') has no variables (other than those bound
 by @(tsee let), @(tsee let*), or @('lambda')), @('rhs') is known to be true in
 the current context, and @('equiv') is typically @('equal') but can be any
 equivalence relation appropriate for the current context (see @(see
 congruence)); then attempt to bind the free variables so that the instantiated
 hypothesis is @('lhs').</p></blockquote>

 <p>For cases (2) and (3), the first instance found may ultimately fail because
 the remaining hypotheses are not all relieved under the extended bindings.  In
 that case, should the attempt to relieve hypotheses fail, or should the search
 continue to find other instances for (2) or (3)?  The answer depends on which
 of two options is in force for the so-called ``match-free'' of the rule.
 Below we discuss how to specify these two options as ``@(':once')'' or
 ``@(':all')'' (the default), respectively.</p>

 <p>Suppose that the original hypothesis is a call of @(tsee force) or @(tsee
 case-split), where forcing is enabled (see @(see enable-forcing)) .  Also
 suppose that one of the following two cases applies: no instances are found for
 (2) and also none for (3), or else the ``match-free'' option for the rule is
 @(':all') (as discussed below) and all attempts ultimately fail for (2)
 and (3) (because the remaining hypotheses are not all relieved).  Then the
 current hypothesis is relieved but in the resulting split-off goals, all free
 variables are bound to unusual names that call attention to this odd
 situation.</p>

 <p>Is it better to specify @(':once') or @(':all')?  We believe that @(':all')
 is generally the better choice because of its greater power, provided the user
 does not introduce a large number of rules with free variables, which has been
 known to slow down the prover due to combinatorial explosion in the search
 (Steps (2) and (3) above).</p>

 <p>Either way, it is good practice to put the ``more substantial'' hypotheses
 first, so that the most likely bindings of free variables will be found first
 (in the case of @(':all')) or found at all (in the case of @(':once')).  For
 example, a rewrite rule like</p>

 @({
  (implies (and (p1 x y)
                (p2 x y))
           (equal (bar x) (bar-prime x)))
 })

 <p>may never succeed if @('p1') is nonrecursive and enabled, since we may well
 not find calls of @('p1') in the current context.  If however @('p2') is
 disabled or recursive, then the above rule may apply if the two hypotheses are
 switched.  For in that case, we can hope for a match of @('(p2 x y)') in the
 current context that therefore binds @('x') and @('y'); then the rewriter's
 full power may be brought to bear to prove @('(p1 x y)') for that @('x') and
 @('y').</p>

 <p>Moreover, the ordering of hypotheses can affect the efficiency of the
 rewriter.  For example, the rule</p>

 @({
  (implies (and (rationalp y)
                (foo x y))
           (equal (bar x) (bar-prime x)))
 })

 <p>may well be sub-optimal.  Presumably the intention is to rewrite @('(bar
 x)') to @('(bar-prime x)') in a context where @('(foo x y)') is explicitly
 known to be true for some rational number @('y').  But @('y') will be bound
 first to the first term found in the current context that is known to
 represent a rational number.  If the 100th such @('y') that is found is the
 first one for which @('(foo x y)') is known to be true, then wasted work will
 have been done on behalf of the first 99 such terms @('y') &mdash; unless
 @(':once') has been specified, in which case the rule will simply fail after
 the first binding of @('y') for which @('(rationalp y)') is known to be true.
 Thus, a better form of the above rule is almost certainly the following.</p>

 @({
  (implies (and (foo x y)
                (rationalp y))
           (equal (bar x) (bar-prime x)))
 })

 <p><i>Specifying `once' or `all'.</i></p>

 <p>As noted above, the following discussion applies only to @(see rewrite),
 @(see linear), and @(see forward-chaining) rules.  See @(see
 free-variables-type-prescription) for a discussion of analogous considerations
 for @(see type-prescription) rules.</p>

 <p>One method for specifying @(':once') or @(':all') for free-variable
 matching is to provide the @(':match-free') field of the @(':rule-classes') of
 the rule, for example, @('(:rewrite :match-free :all)').  See @(see
 rule-classes).  However, there are global events that can be used to specify
 @(':once') or @(':all'); see @(see set-match-free-default) and see @(see
 add-match-free-override).  Here are some examples.</p>

 @({
  (set-match-free-default :once)    ; future rules without a :match-free field
                                    ; are stored as :match-free :once (but this
                                    ; behavior is local to a book)
  (add-match-free-override :once t) ; existing rules are treated as
                                    ; :match-free :once regardless of their
                                    ; original :match-free fields
  (add-match-free-override :once (:rewrite foo) (:rewrite bar . 2))
                                    ; the two indicated rules are treated as
                                    ; :match-free :once regardless of their
                                    ; original :match-free fields
 })

 <p><i>Some history.</i> Before Version 2.7 the ACL2 rewriter performed Step
 (2) above first.  More significantly, it always acted as though @(':once') had
 been specified.  That is, if Step (2) did not apply, then the rewriter took
 the first binding it found using either Steps (1) or (3), in that order, and
 proceeded to relieve the remaining hypotheses without trying any other
 bindings of the free variables of that hypothesis.</p>")

(defxdoc free-variables-examples
  :parents (free-variables)
  :short "Examples pertaining to free variables in rules"
  :long "<p>The examples in the two sub-topics of this topic illustrate the
 handling of free variables in rules of class @(':')@(tsee rewrite)
 (see @(see free-variables-examples-rewrite)) and of class @(':')@(tsee
 forward-chaining) (see @(see free-variables-examples-forward-chaining)),
 respectively.  These implicitly illustrate @(see free-variables) handling in
 rules of class @(':')@(tsee linear) as well.  Also see @(see free-variables)
 and see @(see rule-classes).</p>")

(defxdoc free-variables-examples-forward-chaining
  :parents (free-variables-examples)
  :short "Examples pertaining to free variables in @(see forward-chaining) rules"
  :long "<p>The following examples illustrate ACL2's handling of free variables
 in @(see forward-chaining) rules, as well as user control over how such free
 variables are handled.  See @(see free-variables) for a background
 discussion.</p>

 @({
  ; First let us introduce a transitive operation, op, and prove a
  ; forward-chaining rule stating the transitivity of op.

  (encapsulate
   (((op * *) => *))
   (local (defun op (x y) (< x y)))
   (defthm transitivity-of-op
     (implies (and (op x y) (op y z)) (op x z))
     :rule-classes :forward-chaining))

  ; The following theorem is proved by forward chaining, using the above rule.

  (thm
   (implies (and (op u v) (op v w) (op v a))
            (op u w)))

  ; The proof of the theorem just above succeeds because the term (op u v)
  ; triggers the application of forward-chaining rule transitivity-of-op,
  ; binding x to u and y to v.  Free variable z of that rule is bound to both w
  ; and to a, resulting in the addition of both (op u w) and (op u a) to the
  ; context.  However, (op v a) happens to be at the front of the context, so
  ; if only one free-variable binding had been allowed, then z would have only
  ; been bound to a, not to w, as we now illustrate.

  (add-match-free-override :once (:forward-chaining transitivity-of-op))

  (thm ; FAILS!
   (implies (and (op u v) (op v w) (op v a))
            (op u w)))

  :ubt! 1

  ; Starting over, this time we prove transitivity-of-op as a :match-free :once
  ; forward-chaining rule.  Note that the presence of :match-free eliminates
  ; the free-variables warning that we got the first time.

  (encapsulate
   (((op * *) => *))
   (local (defun op (x y) (< x y)))
   (defthm transitivity-of-op
     (implies (and (op x y) (op y z)) (op x z))
     :rule-classes ((:forward-chaining :match-free :once))))

  (thm ; FAILS!
   (implies (and (op u v) (op v w) (op v a))
            (op u w)))

  ; Notice that if we swap the order of the last two hypotheses the theorem
  ; goes through, because this time (op v w) is first in the context.

  (thm ; SUCCEEDS!
   (implies (and (op u v) (op v a) (op v w))
            (op u w)))

  :u

  ; Now let's try setting the default to :once.

  (set-match-free-default :once)

  ; We still get a free-variables warning when we admit this forward-chaining rule.

  (encapsulate
   (((op * *) => *))
   (local (defun op (x y) (< x y)))
   (defthm transitivity-of-op
     (implies (and (op x y) (op y z)) (op x z))
     :rule-classes ((:forward-chaining))))

  ; This theorem fails -- as it should.

  (thm ; FAILS!
   (implies (and (op u v) (op v w) (op v a))
            (op u w)))

  ; But if we convert this rule (or here, all possible rules) to :all rules,
  ; then the proof succeeds.

  (add-match-free-override :all t)

  (thm ; SUCCEEDS!
   (implies (and (op u v) (op v w) (op v a))
            (op u w)))

  ; Now let's test a relatively slow :all case (the next thm below).

  :ubt! 1

  (encapsulate
   (((op1 *) => *)
    ((op3 * * *) => *))
   (local (defun op1 (x) (declare (ignore x)) t))
   (local (defun op3 (x0 x1 x2)
            (declare (ignore x0 x1 x2))
            t))
   (defthm op1-op3-property
     (implies (and (op1 x0) (op1 x1) (op1 x2))
              (op3 x0 x1 x2))
     :rule-classes ((:forward-chaining :match-free :all))))

  ; The following succeeds, but takes a little time (about a second in one run).

  (thm (implies
        (and (op1 a0) (op1 a1) (op1 a2) (op1 a3) (op1 a4) (op1 a5)
             (op1 a6) (op1 a7) (op1 a8) (op1 a9) (op1 a10) (op1 a11)
             (op1 a12) (op1 a13) (op1 a14) (op1 a15) (op1 a16)
             (op1 a17) (op1 a18) (op1 a19) (op1 a20))
        (op3 a5 a6 a0)))

  (add-match-free-override :once t)

  ; The same theorem now fails because of the add-match-free-override, but is
  ; more than an order of magnitude faster.

  (thm (implies
        (and (op1 a0) (op1 a1) (op1 a2) (op1 a3) (op1 a4) (op1 a5)
             (op1 a6) (op1 a7) (op1 a8) (op1 a9) (op1 a10) (op1 a11)
             (op1 a12) (op1 a13) (op1 a14) (op1 a15) (op1 a16)
             (op1 a17) (op1 a18) (op1 a19) (op1 a20))
        (op3 a5 a6 a0)))

  ; A slight variant succeeds in a negligible amount of time (still with the
  ; :once override above).

  (thm (implies
        (and (op1 a0) (op1 a1) (op1 a2) (op1 a3) (op1 a4) (op1 a5)
             (op1 a6) (op1 a7) (op1 a8) (op1 a9) (op1 a10) (op1 a11)
             (op1 a12) (op1 a13) (op1 a14) (op1 a15) (op1 a16)
             (op1 a17) (op1 a18) (op1 a19) (op1 a20))
        (op3 a5 a20 a20)))

  ; Reality check: This shouldn't give a free-variables warning, and everything
  ; should work great since there are no free variables with this trigger term.

  :ubt! 1

  (encapsulate
   (((op1 *) => *)
    ((op7 * * * * * * *) => *))
   (local (defun op1 (x)
            (declare (ignore x))
            t))
   (local (defun op7 (x0 x1 x2 x3 x4 x5 x6)
            (declare (ignore x0 x1 x2 x3 x4 x5 x6))
            t))
   (defthm op1-op7-property
     (implies (and (op1 x0) (op1 x1) (op1 x2)
                   (op1 x3) (op1 x4) (op1 x5) (op1 x6))
              (op7 x0 x1 x2 x3 x4 x5 x6))
     :rule-classes ((:forward-chaining
                     :trigger-terms ((op7 x0 x1 x2 x3 x4 x5 x6))))))

  ; The following then succeeds, and very quickly.

  (thm (implies (and (op1 a0) (op1 a1) (op1 a2)
                     (op1 a3) (op1 a4) (op1 a5) (op1 a6))
                (op7 a4 a6 a5 a6 a6 a6 a6)))
 })")

(defxdoc free-variables-examples-rewrite
  :parents (free-variables-examples)
  :short "Examples pertaining to free variables in @(see rewrite) rules"
  :long "<p>The following examples illustrate ACL2's handling of free variables
 in @(see rewrite) rules, as well as user control over how such free variables
 are handled.  See @(see free-variables) for a background discussion.</p>

 @({
  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  ;;; Example 1
  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

  (defstub p2 (x y) t) ; introduce unconstrained function

  ; Get warning because of free variable.  This would be an error if you had
  ; first executed (set-match-free-error t) in order to force yourself to
  ; specify :match-free (illustrated later, below).
  (defaxiom p2-trans
    (implies (and (p2 x y)
                  (p2 y z))
             (p2 x z)))

  ; Succeeds.
  (thm (implies (and (p2 a c)
                     (p2 a b)
                     (p2 c d))
                (p2 a d)))

  ; The following causes an error because p2-trans is not a rune.
  (add-match-free-override :once p2-trans)

  ; After the following, the rewrite rule p2-trans will only allow one
  ; attempt per hypothesis to bind free variables.
  (add-match-free-override :once (:rewrite p2-trans))

  ; Now this same theorem fails to be proved.  Here's why.  The
  ; context for proving (p2 a d) happens to include the hypotheses in
  ; reverse order.  So when the first hypothesis of p2-trans, namely
  ; (p2 x y), is relieved, where x is bound to a (as we are attempting
  ; to rewrite the current literal (p2 a d)), we find (p2 a b) in the
  ; context before (p2 a c) and hence y is bound to b.  The
  ; instantiated second hypothesis of p2-trans is thus (p2 b d), and
  ; the proof fails.  Before the add-match-free-override form above,
  ; the proof succeeded because the rewriter was allowed to backtrack
  ; and find the other binding for the first hypothesis of p2-trans,
  ; namely, y bound to c.  Then the instantiated second hypothesis of
  ; p2-trans is (p2 c d), which is known to be true in the current
  ; context.
  (thm (implies (and (p2 a c)
                     (p2 a b)
                     (p2 c d))
                (p2 a d)))

  ; Return to original behavior for binding free variables.
  (add-match-free-override :all t)

  ; Succeeds once again.
  (thm (implies (and (p2 a c)
                     (p2 a b)
                     (p2 c d))
                (p2 a d)))

  (u) ; undo (add-match-free-override :all t)

  ; This is an error, since no further arguments should appear after
  ; :clear.
  (add-match-free-override :clear t)

  ; Return all rules to original behavior for binding free variables,
  ; regardless of which previous add-match-free-override forms have
  ; been executed.
  (add-match-free-override :clear)

  ; This succeeds just as it did originally.
  (thm (implies (and (p2 a c)
                     (p2 a b)
                     (p2 c d))
                (p2 a d)))

  (ubt! 'p2-trans) ; back to the start, except retain the defstub

  ; Require that :match-free be specified for :linear and :rewrite rules with
  ; free variables.
  (set-match-free-error t)

  ; Fails because :match-free is missing.
  (defaxiom p2-trans
    (implies (and (p2 x y)
                  (p2 y z))
             (p2 x z)))

  ; Fails because :match-free must be followed by :once or :all.
  (defaxiom p2-trans
    (implies (and (p2 x y)
                  (p2 y z))
             (p2 x z))
    :rule-classes ((:rewrite :match-free nil)))

  ; Succeeds, this time with no warning at all.
  (defaxiom p2-trans
    (implies (and (p2 x y)
                  (p2 y z))
             (p2 x z))
    :rule-classes ((:rewrite :match-free :once)))

  ; Fails because we only bind once (see earlier long comment).
  (thm (implies (and (p2 a c)
                     (p2 a b)
                     (p2 c d))
                (p2 a d)))

  ; Treat p2-trans as though `:match-free :all' had been specified.
  (add-match-free-override :all (:rewrite p2-trans))

  ; Succeeds since more than one binding is allowed for p2-trans.
  (thm (implies (and (p2 a c)
                     (p2 a b)
                     (p2 c d))
                (p2 a d)))

  (u)
  (u)

  ; Specify that future :linear and :rewrite rules with free variables
  ; that do not have :match-free specified are treated as though
  ; `:match-free :once' were specified.
  (set-match-free-default :once)

  ; Succeeds without error since `:match-free' is specified, as described
  ; above.  But there is a warning, since :match-free is not specified for this
  ; :rewrite rule.
  (defaxiom p2-trans
    (implies (and (p2 x y)
                  (p2 y z))
             (p2 x z)))

  ; Fails since only single bindings are allowed for p2-trans.
  (thm (implies (and (p2 a c)
                     (p2 a b)
                     (p2 c d))
                (p2 a d)))

  ; Treat p2-trans as though `:match-free :all' had been specified.
  (add-match-free-override :all t)

  ; Succeeds.
  (thm (implies (and (p2 a c)
                     (p2 a b)
                     (p2 c d))
                (p2 a d)))

  ; Test searching of ground units, i.e. rewrite rules without variables on the
  ; left side of the conclusion, for use in relieving hypotheses with free
  ; variables.  This is a very contrived example.

  (ubt! 1) ; back to the start

  (encapsulate
   (((p1 *) => *)
    ((p2 * *) => *)
    ((p3 *) => *)
    ((a) => *)
    ((b) => *))
   (local (defun p1 (x) x))
   (local (defun p2 (x y) (list x y)))
   (local (defun p3 (x) x))
   (local (defun a () 0))
   (local (defun b () 0)))

  ; Allow default of :match-free :all (form may be omitted).
  (set-match-free-error nil)

  (defaxiom ax1
    (implies (and (p2 x y)
                  (p1 y))
             (p3 x)))

  (defaxiom p2-a-b
    (p2 (a) (b)))

  (defaxiom p2-a-a
    (p2 (a) (a)))

  (defaxiom p1-b
    (p1 (b)))

  ; Succeeds; see long comment below on next attempt to prove this
  ; theorem.
  (thm (implies (p2 (a) y)
                (p3 (a))))

  ; Now ax1 will only relieve hypothesis (p2 x y) for one binding of y:
  (add-match-free-override :once t)

  ; Fails when ax1 attempts to rewrite the conclusion to true, because
  ; the most recent ground unit for hypothesis (p2 x y) with x bound
  ; to (a) is rule p2-a-a, which binds y to (a).  If more than one ground
  ; unit could be used then we would backtrack and apply rule p2-a-b,
  ; which binds y to (b) and hence hypothesis (p1 y) of ax1 is
  ; relieved by rule p1-b.
  (thm (implies (p2 (a) y)
                (p3 (a))))

  ; Return rules to original :match-free behavior.
  (add-match-free-override :clear)

  ; Succeeds once again.
  (thm (implies (p2 (a) y)
                (p3 (a))))

  ; Just for kicks, change the behavior of a built-in rule irrelevant
  ; to the proof at hand.
  (add-match-free-override :once (:rewrite string<-l-trichotomy))

  ; Still succeeds.
  (thm (implies (p2 (a) y)
                (p3 (a))))
 })

 @({
  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  ;;; Example 2
  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 })

 <p>The next example illustrates the use of the @(see break-rewrite) facility
 to get information about handling of free variables by the rewriter.
 Explanation is given after this (edited) transcript.  Input begins on lines
 with a prompt (search for ``ACL2''); the rest is output.</p>

 @({
  ACL2 !>(encapsulate
          ((p1 (u x) t)
           (bad (x) t)
           (p2 (x y z) t)
           (bar (x y) t)
           (foo (x y) t)
           (poo (x y) t)
           (prop (u) t))

          (local (defun p1 (u x) (declare (ignore u x)) nil))
          (local (defun bad (x) (declare (ignore x)) nil))
          (local (defun p2 (x y z) (declare (ignore x y z)) nil))
          (local (defun bar (x y) (declare (ignore x y)) nil))
          (local (defun foo (x y) (declare (ignore x y)) nil))
          (local (defun poo (x y) (declare (ignore x y)) nil))
          (local (defun prop (u) (declare (ignore u)) t))

          (defthm foo-poo
            (implies (syntaxp (equal y 'y3))
                     (equal (foo x y)
                            (poo x y))))

          (defthm lemma-1
            (implies (and (p1 u x)
                          (bad x)
                          (p2 x y z)
                          (bar x y)
                          (equal x x) ; admittedly silly!
                          (foo x y))
                     (prop u))
            :rule-classes ((:rewrite :match-free :all))))

  ; [[ output omitted ]]

  Summary
  Form:  ( ENCAPSULATE ((P1 ...) ...) ...)
  Rules: NIL
  Warnings:  Subsume and Non-rec
  Time:  0.08 seconds (prove: 0.00, print: 0.01, other: 0.06)
   T
  ACL2 !>:brr t
  The monitored runes are:
  NIL
   T
  ACL2 !>:monitor (:rewrite lemma-1) t
  (((:REWRITE LEMMA-1) 'T))
  ACL2 !>(thm (implies (and (p1 u0 x1)
                            (bad x1)
                            (bad x3)
                            (bar x3 y1)
                            (bar x3 y3)
                            (p1 u0 x2)
                            (p1 u0 x3)
                            (p2 x3 y1 z1)
                            (p2 x3 y3 z1))
                       (prop u0)))

  (1 Breaking (:REWRITE LEMMA-1) on (PROP U0):
  1 ACL2 >:eval

  1x (:REWRITE LEMMA-1) failed because :HYP 1 contains free variables.
  The following display summarizes the attempts to relieve hypotheses
  by binding free variables; see :DOC free-variables.

      [1] X : X1
  Failed because :HYP 3 contains free variables Y and Z, for which no
  suitable bindings were found.
      [1] X : X2
  Failed because :HYP 2 rewrote to (BAD X2).
      [1] X : X3
          [3] Z : Z1
              Y : Y1
  Failed because :HYP 6 rewrote to (FOO X3 Y1).
          [3] Z : Z1
              Y : Y3
  Failed because :HYP 6 rewrote to (POO X3 Y3).

  1 ACL2 >:unify-subst
       U : U0
  1 ACL2 >
 })

 <p>The @(':eval') command above asks the rewriter to attempt to apply the
 rewrite rule @('lemma-1') to the term @('(prop u0)'), shown just above the
 line with @(':eval').  As we can see at the end, the variable @('u') in the
 conclusion of @('lemma-1') is being bound to the variable @('u0') in the
 conjecture.  The first hypothesis of @('lemma-1') is @('(p1 u x)'), so the
 rewriter looks for some @('x') for which @('(p1 u0 x)') is known to be true.
 It finds @('x1'), and then goes on to consider the second hypothesis, @('(bad
 x)').  Since the theorem we are proving has @('(bad x1)') in the hypothesis
 and @('x') is currently bound to @('x1'), the rewriter is satisfied and moves
 on to the third hypothesis of @('lemma-1'), @('(p2 x y z)').  However, @('x')
 is bound to @('x1') and there are no instances of @('y') and @('z') for which
 @('(p2 x1 y z)') is known in the current context.  All of the above analysis
 is summarized in the first part of the output from @(':eval') above:</p>

 @({
      [1] X : X1
  Failed because :HYP 3 contains free variables Y and Z, for which no
  suitable bindings were found.
 })

 <p>Thus, the binding of @('x') to @('x1') on behalf of the first hypothesis
 has failed.</p>

 <p>The rewriter now backs up to look for other values of @('x') that satisfy
 the first hypothesis, and finds @('x2') because our current theorem has a
 hypothesis of @('(p1 u0 x2)').  But this time, the second hypothesis of
 @('lemma-1'), @('(bad x)'), is not known to be true for @('x'); that is,
 @('(bad x2)') does not rewrite to @('t'); in fact, it rewrites to itself.
 That explains the next part of the output from @(':eval') above:</p>

 @({
      [1] X : X2
  Failed because :HYP 2 rewrote to (BAD X2).
 })

 <p>The rewriter now backs up again to look for other values of @('x') that
 satisfy the first hypothesis, and finds @('x3') because our current theorem
 has a hypothesis of @('(p1 u0 x3)').  This time, the second hypothesis of
 @('lemma-1') is not a problem, and moreover, the rewriter is able to bind
 @('y') and @('z') to @('y1') and @('z1'), respectively, in order to satisfy
 the third hypothesis, @('(p2 x y z)'): that is, @('(p2 x2 y1 z1)') is known in
 the current context.  That explains more of the above output from
 @(':eval'):</p>

 @({
      [1] X : X3
          [3] Z : Z1
              Y : Y1
 })

 <p>Unfortunately, the sixth hypothesis, @('(foo x y)'), rewrites to itself
 under the above bindings:</p>

 @({
  Failed because :HYP 6 rewrote to (FOO X3 Y1).
 })

 <p>So the rewriter looks for other bindings to satisfy the third hypothesis
 and finds these.</p>

 @({
          [3] Z : Z1
              Y : Y3
 })

 <p>This time, the sixth hypothesis can be rewritten under the above bindings,
 from @('(foo x3 y3)') to @('(poo x3 y3)') by lemma @('foo-poo'), but still not
 to @('t').</p>

 @({
  Failed because :HYP 6 rewrote to (POO X3 Y3).
 })

 <p>There are no more free variable bindings to try, so this concludes the
 output from @(':eval').</p>

 @({
  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  ;;; Example 3
  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 })

 <p>The next pair of examples illustrates so-called ``binding hypotheses'' (see
 @(see free-variables)) and explores some of their subtleties.  The first shows
 binding hypotheses in action on a simple example.  The second shows how
 binding hypotheses interact with equivalence relations and explains the role
 of @(tsee double-rewrite).</p>

 <p>Our first example sets up a theory with two user-supplied rewrite rules,
 one of which has a binding hypothesis.  Below we explain how that binding
 hypothesis contributes to the proof.</p>

 @({
  ; Define some unary functions.
  (defun f (x) (declare (ignore x)) t)
  (defun g (x) x)
  (defun h (x) x)
  (defun k (x) x)

  ; Prove some simple lemmas.  Note the binding hypothesis in g-rewrite.
  (defthm f-k-h
    (f (k (h x))))
  (defthm g-rewrite
         (implies (and (equal y (k x)) ; binding hypothesis
                       (f y))
                  (equal (g x) y)))

  ; Restrict to a theory that includes the above lemmas but avoids the above
  ; definitions.
  (in-theory (union-theories (theory 'minimal-theory)
                             '(f-k-h g-rewrite)))

  ; Prove a theorem.
  (thm (equal (g (h a)) (k (h a))))
 })

 <p>Let us look at how ACL2 uses the above binding hypothesis in the proof of
 the preceding @('thm') form.  The rewriter considers the term @('(g (h a))')
 and finds a match with the left-hand side of the rule @('g-rewrite'), binding
 @('x') to @('(h a)').  The first hypothesis binds @('y') to the result of
 rewriting @('(k x)') in the current context, where the variable @('x') is
 bound to the term @('(h a)'); thus @('y') is bound to @('(k (h a))').  The
 second hypothesis, @('(f y)'), is then rewritten under this binding, and the
 result is @('t') by application of the rewrite rule @('f-k-h').  The rule
 @('g-rewrite') is then applied under the already-mentioned binding of @('x')
 to @('(h a)').  This rule application triggers a recursive rewrite of the
 right-hand side of @('g-rewrite'), which is @('y'), in a context where @('y')
 is bound (as discussed above) to @('(k (h a))').  The result of this rewrite
 is that same term, @('(k (h a))').  The original call of @('equal') then
 trivially rewrites to @('t').</p>

 <p>We move on now to our second example, which is similar but involves a
 user-defined equivalence relation.  You may find it helpful to review
 @(':equivalence') rules; see @(see equivalence).</p>

 <p>Recall that when a hypothesis is a call of an equivalence relation other
 than @('equal'), the second argument must be a call of @(tsee double-rewrite)
 in order for the hypothesis to be treated as a binding hypothesis.  That is
 indeed the case below; an explanation follows.</p>

 @({
  ; Define an equivalence relation.
  (defun my-equiv (x y) (equal x y))
  (defequiv my-equiv) ; introduces rule MY-EQUIV-IS-AN-EQUIVALENCE

  ; Define some unary functions
  (defun f (x) (declare (ignore x)) t)
  (defun g (x) x)
  (defun h1 (x) x)
  (defun h2 (x) x)

  ; Prove some simple lemmas.  Note the binding hypothesis in lemma-3.
  (defthm lemma-1
    (my-equiv (h1 x) (h2 x)))
  (defthm lemma-2
    (f (h2 x)))
  (defthm lemma-3
         (implies (and (my-equiv y (double-rewrite x)) ; binding hypothesis
                       (f y))
                  (equal (g x) y)))

  ; Restrict to a theory that includes the above lemmas but avoids the above
  ; definitions.
  (in-theory (union-theories (theory 'minimal-theory)
                             '(lemma-1 lemma-2 lemma-3
                                       my-equiv-is-an-equivalence)))

  ; Prove a theorem.
  (thm (equal (g (h1 a)) (h2 a)))
 })

 <p>The proof succeeds much as in the first example, but the following
 observation is key: when ACL2 binds @('y') upon considering the first
 hypothesis of @('lemma-3'), it rewrites the term @('(double-rewrite x)') in a
 context where it need only preserve the equivalence relation @('my-equiv').
 At this point, @('x') is bound by applying @('lemma-3') to the term @('(g (h1
 a))'); so, @('x') is bound to @('(h1 a)').  The rule @('lemma-1') then applies
 to rewrite this occurrence of @('x') to @('(h2 a)'), but only because it
 suffices to preserve @('my-equiv').  Thus @('y') is ultimately bound to @('(h2
 a)'), and the proof succeeds as one would expect.</p>

 <p>If we tweak the above example slightly by disabling the user's @(see
 equivalence) @(see rune), then the proof of the @(tsee thm) form fails because
 the above rewrite of @('(double-rewrite x)') is done in a context where it no
 longer suffices to preserve @('my-equiv') as we dive into the second argument
 of @('my-equiv') in the first hypothesis of @('lemma-3'); so, @('lemma-1')
 does not apply this time.</p>

 @({
  (in-theory (union-theories (theory 'minimal-theory)
                             '(lemma-1 lemma-2 lemma-3)))

  ; Proof fails in this case!
  (thm (equal (g (h1 a)) (h2 a)))
 })")

(defxdoc free-variables-type-prescription
  :parents (free-variables)
  :short "Matching for free variable in @(see type-prescription) rules"
  :long "<p>We assume familiarity with the issue of dealing with free variables
 in hypotheses; see @(see free-variables).</p>

 <p>By default, starting with Version 4.3, ACL2 attempts all possible matches
 for free variables.  Consider the following example.</p>

 @({
  (defstub f1 (x) t)
  (defstub f2 (x y) t)
  (defstub f3 (y) t)

  (defaxiom f1-prop
    (implies (and (f2 x y) ; <-- y is free in this hypothesis
                  (f3 y))
             (f1 x))       ; <-- (f1 x) is the type-term (type is `non-nil')
    :rule-classes :type-prescription)

  ; Succeeds:
  (thm (implies (and (f2 a b)
                     (f3 b))
                (f1 a)))

  ; The following fails unless we try more than one match for free variables in
  ; hypotheses.
  (thm (implies (and (f2 a b)
                     (f2 a c)
                     (f2 a d)
                     (f3 b))
                (f1 a)))
 })

 <p>There may be times when you want to match only the first free variable.  In
 that case, you can write a function of two arguments, the
 <i>type-prescription</i> @(see rune) being applied and the current ACL2 world,
 that prohibits multiple matching for those times.  Your function is then
 `attached' to the built-in constrained function, @('oncep-ts').  The following
 examples are intended to explain how this works.</p>

 <p>First, let us disallow all multiple matching of free variables (i.e.,
 implement the behavior often referred to as ``@(':match-free :once')''; see
 @(see free-variables)).</p>

 @({
  (defun oncep-tp-always (rune wrld)
    (declare (ignore rune wrld)
             (xargs :mode :logic :guard t))
    t)

  (defattach-system oncep-tp oncep-tp-always)
 })

 <p>The second @('thm') form above will now fail, because only one
 free-variable match is permitted for the first hypothesis of rule @('f1-prop')
 above.</p>

 <p>Now suppose that instead, we want to disallow multiple matches for free
 variables in hypotheses of type-prescription rules <i>except</i> for the rule
 @('f1-prop') above.  With the following events, the second @('thm') form above
 once again succeeds.</p>

 @({
  (defun oncep-tp-always-except-f1-prop (rune wrld)
    (declare (ignore wrld)
             (xargs :mode :logic :guard (and (consp rune)
                                             (consp (cdr rune))
                                             (symbolp (cadr rune)))))
    (not (eq (base-symbol rune) 'f1-prop)))

  (defattach-system oncep-tp oncep-tp-always-except-f1-prop)
 })

 <p>In general, your @(tsee defattach) event will attach a function symbol to
 @('oncep-tp').  The @(see guard) of that function symbol must be implied by
 the guard of @('oncep-tp'):</p>

 @({
  ACL2 !>:args oncep-tp

  Function         ONCEP-TP
  Formals:         (RUNE WRLD)
  Signature:       (ONCEP-TP * *)
                   => *
  Guard:           (AND (PLIST-WORLDP WRLD)
                        (CONSP RUNE)
                        (CONSP (CDR RUNE))
                        (SYMBOLP (CADR RUNE)))
  Guards Verified: T
  Defun-Mode:      :logic
  Type:            built-in (or unrestricted)

   ONCEP-TP
  ACL2 !>
 })")

(defxdoc frequently-asked-questions-by-newcomers
  :parents (introduction-to-the-theorem-prover)
  :short "Some questions newcomers frequently ask"
  :long "<p>This FAQ is for people who've read through all the other sections
 of the tutorial introduction to the theorem prover (see @(see
 introduction-to-the-theorem-prover) and all the links from it that are not
 marked with the little warning sign (``<see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>'').
 Do not expect to understand our answers if you haven't taken the time to read
 through the tutorial.  In the answers below you will see more links into the
 hypertext reference manual.  While such links were marked ``<see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>''
 in the tutorial, they are not marked that way here.  When you enter the
 reference manual be prepared to explore and assemble a mini-course on the
 topic of interest, not a quick fix.</p>

 <p><b>Q</b>.  How do I find something in the <b>ACL2 documentation</b>?
 <b>A</b>.  Try the ``Jump to'' or ``Search'' boxes at the <a
 href='https://acl2.org/doc/index.html'>ACL2+Books Manual</a>.</p>

 <p><b>Q</b>.  How does the theorem prover work?  <b>A</b>.  We really don't
 think you need to know much about the inner workings of the prover to become
 an effective user.  That doesn't mean the system is self-explanatory!  It
 means that stuff you need to learn is not how the theorem prover works but how
 to interact with it!  That is what @(see introduction-to-the-theorem-prover)
 is about.  However, if you want the most basic overview of the prover, see
 @(see architecture-of-the-prover).</p>

 <p><b>Q</b>. How do I <b>define a new function</b>?  <b>A</b>. See @(see
 defun).</p>

 <p><b>Q</b>. How do I <b>define a new predicate</b>?  <b>A</b>. See @(see
 defun).</p>

 <p><b>Q</b>. How do I <b>define a new relation</b>?  <b>A</b>. See @(see
 defun).</p>

 <p><b>Q</b>. How do I define a <b>function or predicate that takes a varying
 number of arguments</b>?  <b>A</b>. You can't.  However, see @(see defmacro)
 to learn how to define a macro that takes a varying number of arguments and
 expands into an arbitrary term that you compute.</p>

 <p><b>Q</b>. How do I define a <b>macro that is sensitive to the state</b>?
 <b>A</b>.  You can't.  However, advanced users should consider @(tsee
 make-event).</p>

 <p><b>Q</b>. How do I define <b>mutually recursive</b> functions?  <b>A</b>.
 See @(see mutual-recursion).  However, you should realize that when two
 functions, say @('f') and @('g'), are mutually recursive, properties of @('f')
 generally have to be stated simultaneously with properties of @('g'), since
 inductive proofs about one function require inductive hypotheses about the
 other.  Furthermore, ACL2 does not know how to do inductions for mutually
 recursive functions and must be told.  See @(see
 mutual-recursion-proof-example).</p>

 <p><b>Q</b>. How do I declare the <b>type signature of a function</b>?
 <b>A</b>.  You can't.  ACL2 is a syntactically untyped language and all
 functions are defined on all objects in the ACL2 universe.  We recommend that
 the new user get used to this and only then explore the use of ACL2 to express
 and enforce a type regime.  In ACL2, the <i>guard</i> of a function is akin to
 the type signature of a function in typed languages.  However, ACL2 guards may
 be arbitrary terms, not just type conditions, they only concern the inputs to
 the function (not its result), and do not affect the axiom defining the
 function &mdash; all functions are defined on every combination of objects.
 You may, of course, prove theorems that establish that every function called
 in a definition or theorem is supplied with input satisfying its guards (which
 necessarily involves describe the outputs too).  These formulas are called
 <i>guard conjectures</i> and the process of proving them is called <i>guard
 verification</i>.  Since guards are arbitrary ACL2 formulas, the ``type
 regimes'' one tends to enforce in ACL2 can be much for flexible and expressive
 than those in most programming languages.  However, that expressibility also
 means guard verification can be challenging (indeed undecidable).  On the
 other hand, if one limits oneself to simple type-like guards, lemmas can be
 proved that make most guard verification fully automatic and one can configure
 ACL2 to do guard verification automatically at @('defun')-time.  One may also
 delay guard verification until ``the right'' lemmas have been proved.  By
 doing guard verification one can make functions execute faster by allowing the
 code to avoid runtime checks.  This is especially valuable to industrial users
 who have large models used both in verification and as simulation engines for
 designed artifacts.  In addition, guard verification can give you the
 assurance that you are using your functions within their intended domains and
 hence is a form of functional specification and verification.  However, all
 these advantages aside, it is remarkably easy to drift away from the simplest
 type regimes and write a guard that raises deep mathematical problems.  New
 users should not try to confront these problems until they are comfortable
 with the theorem prover and with lemma development.  Therefore, we
 <b>strongly</b> recommend that you forget about types and guards and get used
 to reasoning about total functions.  When you do decide to learn about them,
 be prepared for a complex story involving specification, execution efficiency,
 and proof management.  See @(see guard).</p>

 <p><b>Q</b>. How do I tell @('defun') <b>what measure to use</b>?
 <b>A</b>. See @(see xargs), specifically @(':measure').</p>

 <p><b>Q</b>.  I specified a measure that always returns a natural number but
 ACL2 is acting like it's not a natural number.  <b>A</b>.  There are two
 likely problems.  The most likely one is that your measure isn't really always
 a natural!  Suppose the formals of your @('defun') are @('x') and @('y') and
 your measure is @('(m x y)').  Suppose the recursive calls of your function
 are protected by tests that ensure that @('x') and @('y') are naturals.  Then
 you might assume @('x') and @('y') are naturals in the measure.  But ACL2 has
 to prove @('(o-p (m x y))'), where @(tsee o-p) is the predicate that
 recognizes ordinals (and naturals are ordinals).  Note that the theorem
 doesn't have any hypotheses!  You might intuitively think that your measure
 has to be an ordinal just under the conditions that lead to recursive calls.
 That's not what ACL2 enforces.  It has to be an ordinal, always.  So you must
 change your specified measure.  For example, consider wrapping @(tsee nfix)
 around it or around its uses of @('x') and @('y') to coerce those quantities
 to naturals.  The second most likely explanation is that your measure returns
 a natural, always, but ACL2 doesn't know that and it takes induction to prove.
 This might happen if @('m') involves some recursive functions.  In this case,
 prove @('(natp (m x y))') before your @('defun').  Perhaps you should consider
 making the @('natp') lemma a @(':')@(tsee type-prescription) lemma to make
 ACL2's typing algorithm aware of it.</p>

 <p><b>Q</b>. How do I tell @('defun') <b>what well-founded relation to
 use</b>?  <b>A</b>. See @(see xargs), specifically
 @(':well-founded-relation').</p>

 <p><b>Q</b>. How do I show that a <b>relation is well-founded</b>?
 <b>A</b>. Prove a theorem establishing that there is an order preserving
 embedding into the ordinals and store it with @(':rule-classes')
 @(':well-founded-relation') @(see well-founded-relation-rule).</p>

 <p><b>Q</b>.  What is an <b>ordinal</b>?  What does it mean to be
 <b>well-founded</b>?  <b>A</b>.  Ordinals are an extension of the natural
 numbers used to ensure that a process can't go on forever.  Like naturals,
 they can be added, multiplied, and exponentiated.  There is a sense of one
 ordinal being less than another.  Unlike the naturals, each of which is
 finite, the ordinals include infinite objects.  Now imagine ``standing'' on an
 ordinal and ``stepping'' to a smaller one.  Like the naturals, this ``walk
 down the ordinals'' can't go on forever, even if you start on an infinite
 ordinal.  That is because the ordinals are <i>well-founded</i>.  See @(tsee
 o-p) for more information about ordinals in ACL2 and about well-foundedness.
 See @(see ordinals) for a deeper discussion and a discussion of books that can
 help configure ACL2 to reason about ordinals.</p>

 <p><b>Q</b>. How can provide <b>hints for the termination proofs</b> in
 @('defun')?  <b>A</b>. See @(see xargs), specifically @(':hints') (for the
 termination proofs) and @(':guard-hints') (for the guard verification
 proofs).</p>

 <p><b>Q</b>. How do I define a <b>constant</b> (something like a <b>global
 variable</b>)?  <b>A</b>. See @(see defconst).  But remember that as an
 applicative programming language, ACL2 does not have global variables!  You
 can define a symbol to have a fixed value and use the symbol sort of like a
 global variable in function definitions: you may refer to the value of the
 symbol in your functions without passing the variable in as formal parameter.
 But you may not ever change the value of the symbol!</p>

 <p><b>Q</b>. How do I save the value of a top-level computation for future
 use?  <b>A</b>. See @(see assign) and see @(see @).</p>

 <p><b>Q</b>. How do I introduce <b>new syntactic form</b> or
 <b>abbreviation</b>?  <b>A</b>. See @(see defmacro).</p>

 <p><b>Q</b>.  How can create and modify an array?  <b>A</b>.  ACL2 is a
 functional language, so it is impossible to destructively modify an existing
 object; technically, all ``updates'' to objects must be implemented by
 ``copy-on-write'' semantics.  That said, ACL2 provides support for @(see
 arrays), provided you use them in a restricted way.  They give you
 constant-time access and change under the use restrictions.</p>

 <p><b>Q</b>.  How do I read from or write to a file?  How do I do IO?
 <b>A</b>.  To manipulate files, your function must have @(tsee state) as an
 argument, so you should read about the restrictions that imposes.  For
 input/output facilities, see @(see io).</p>

 <p><b>Q</b>. How do I define a <b>structure that can be destructively
 modified</b>?  <b>A</b>. ACL2 is an <i>applicative programming language</i>.
 You can't modify objects arbitrarily!  You basically have to ``copy on
 write,'' which means you construct new objects from old ones, making the
 changes you want in the new one.  If the @('car') of some object is @('1') at
 one moment and @('2') later, then the basic logical axiom @('(car x)') =
 @('(car x)') is violated!  However, if the only reference to the old object,
 e.g., <i>x</i>, was to pass it to the code that copied and ``changed'' it,
 then ACL2 can re-use the old object to produce the new one and the axioms
 would not object.  Such syntactic restrictions can make <i>x</i> a modifiable
 structure but they will impose a heavy burden on you as a programmer: if pass
 such an <i>x</i> to a function and the function modifies it, then you must
 pass <i>x</i> only to that function and you must return the modified value and
 use it henceforth.  Such objects are said to be <i>single threaded</i>.  See
 @(see defstobj).</p>

 <p><b>Q</b>.  How do I write a universal quantifier?  An existential
 quantifier?  How can I say ``for all'' or ``there exists''?  <b>A</b> You
 can't literally write quantifiers.  But ACL2 has the power of full first order
 logic with quantification.  See @(see quantifiers).</p>

 <p><b>Q</b>.  How do I introduce an undefined or uninterpreted function
 symbol?  Can I constrain it to have certain properties?  <b>A</b>.  See @(see
 encapsulate).</p>

 <p><b>Q</b>.  How can I hide a lemma?  I want to prove a lemma temporarily to
 use in another proof but I don't want the lemma around thereafter.  <b>A</b>.
 One way to get a similar effect is to prove the lemma and then disable it with
 an @('(in-theory (disable ...))') event; see @(see in-theory).  Another way is
 to put the lemma and the theorem that needs it into an @(tsee encapsulate) and
 wrap a @(tsee local) around the lemma.</p>

 <p><b>Q</b>. What is an <b>event</b>?  <b>A</b>. An <i>event</i> is a command
 that adds information to the ACL2 database (the ``logical world''), like
 @('defun') or @('defthm').  See @(see events).</p>

 <p><b>Q</b>. How do I say that I <b>do not want a rewrite rule</b> generated
 from a theorem?  <b>A</b>. The command</p>

 <code>
 (defthm <i>name</i> <i>formula</i>
         :rule-classes nil)
 </code>

 <p>will attempt to prove <i>formula</i> and, if successful, give
 <i>formula</i> the name <i>name</i>, which you may use in hints as a theorem,
 but it will build no rules from the formula.</p>

 <p><b>Q</b>. How do I say that I want a formula to be <b>stored as a rewrite
 rule</b>?  <b>A</b>. The command</p>

 <code>
 (defthm <i>name</i> <i>formula</i>)
 </code>

 <p>will attempt to prove <i>formula</i> and, if successful, it will give
 <i>formula</i> the name <i>name</i> and generate a rewrite rule from it, with
 the runic name @('(:rewrite ')<i>name</i>)].  It could happen that
 <i>formula</i> generates more than one rewrite rule, e.g., this happens if the
 conclusion is an @('AND').  In this case, each conjunctive branch through the
 conclusion generates a rule named @('(:rewrite ')<i>name</i>@(' . i)'), for
 <i>i</i>=1,2,...  For more details, see @(see rewrite).</p>

 <p><b>Q</b>. How do I say that I want a formula to be <b>stored as a rewrite
 rule</b> <b>and some other kinds of rules</b>?  <b>A</b>. The command</p>

 <code>
 (defthm <i>name</i> <i>formula</i>
         :rule-classes (<i>:class1</i> ... <i>classk</i>))
 </code>

 <p>will attempt to prove <i>formula</i> and, if successful, it will give
 <i>formula</i> the name <i>name</i> and generate a rule of each <i>:classi</i>
 specified.  Each <i>:classi</i> should either be a keyword, like @(':REWRITE')
 or @(':GENERALIZE'), naming a rule class (see @(see rule-classes)), or else
 should be a list that starts with a rule class and then lists the relevant
 modifiers.  Be sure to include @(':REWRITE') among the rule classes if you
 want the formula to generate a rewrite rule.  It doesn't do that automatically
 if you explicitly specify @(':rule-classes')!</p>

 <p><b>Q</b>. How do I <b>rearrange</b> the shape of a formula before
 generating a rule from it?  <b>A</b>. See @(see rule-classes) and read about
 the @(':corollary') modifier.</p>

 <p><b>Q</b>. What is a <b>type-prescription</b>?  <b>A</b>. ACL2 has an
 algorithm for determining the type of object returned by a term, where a type
 is one of the Common Lisp primitive datatypes such as natural, integer,
 Boolean, cons, true-listp, etc.  Rules provided by you can influence this
 algorithm.  See @(see type-prescription).</p>

 <p><b>Q</b>. How do <b>rewrite rules work</b>?  <b>A</b>. Re-read the tutorial
 sections: @(see introduction-to-rewrite-rules-part-1) and @(see
 introduction-to-rewrite-rules-part-2).</p>

 <p><b>Q</b>. How do I <b>see what's in the database</b>?  <b>A</b>. You can't
 look at the entire database with user-friendly tools.  You can print the
 command that introduced a particular name, print the entire sequence of user
 commands, print the commands in the region between two commands, print all the
 rewrite rules that apply to a given term or function symbol, and many other
 options.  See @(see history).  If you have loaded a book from another user,
 you might wish to read the source file.  For example, the source file for
 @('(include-book "arithmetic-5/top" :dir :system)') is the file named
 @('arithmetic-5/top.lisp') on the @('acl2-sources/books/') directory where
 ever your ACL2 sources are installed.  Often, books are well-documented by
 comments by their authors.  Some books have @('Readme') or @('README') files
 on the same directory.</p>

 <p><b>Q</b>. How do I <b>undo</b> a command?  <b>A</b>. See @(see history),
 especially see @(see u) (``undo'') and see @(see ubt) (``undo back
 through''). <b>Q</b>. What <b>rewrite rules match</b> a given term?
 <b>A</b>. See @(see pl).</p>

 <p><b>Q</b>.  What were those <b>questions to ask when looking at key
 checkpoints</b>?  <b>A</b>.  See @(see introduction-to-key-checkpoints).</p>

 <p><b>Q</b>. How do I figure out <b>why a rewrite rule won't fire</b>?
 <b>A</b>. If you activate rewrite rule monitoring (see @(see brr)) and then
 install a monitor (see @(see monitor)) on the rule in question, ACL2 will
 enter an interactive break whenever the pattern of the rule is matched against
 a target in a proof.  So after installing the monitor, re-try the proof and
 then interact with the rewriter via break commands (see @(see brr-commands)).
 Like all trace and break packages, you have to know what you're doing to use
 the break rewrite facility, so read the material in the reference manual.  If
 no interactive break happens after you've installed the monitor on your rule
 and re-tried the proof, it means no suitable target ever arose.  Don't forget
 to turn off monitoring when you're done as it slows down the system.</p>

 <p><b>Q</b>. <b>Why is a proof taking so long?</b> <b>A</b>. Unexpectedly poor
 performance on simple problems is usually a sign of cyclic rewriting or
 combinatoric explosion.  See @(see dmr) and see @(see
 accumulated-persistence).</p>

 <p><b>Q</b>. How do I tell ACL2 <b>what induction to do</b> for a particular
 formula?  <b>A</b>. When issuing the @('defthm') command for the formula,
 supply an @(':induct') hint:</p>

 <code>
 (defthm <i>name</i>
         <i>formula</i>
         :hints (("Goal" :induct (f x1 ... xn))))
 </code>

 <p>where @('f') is a function that recurs the way you want the induction to
 unfold and @('x1 ... xn') are the relevant variables in <i>formula</i>.  You
 usually have to define @('f') appropriately for each formula that needs an
 induct hint, though sometimes you can re-use an earlier @('f') or one of the
 functions in the formula itself.  It doesn't matter what value @('(f x1
 ... xn)') returns.  All that matters is how it recurs.  The termination
 analysis for @('f') justifies the induction done.  See @(see hints),
 especially the section on @(':induct') hints; also see @(see induction).</p>

 <p><b>Q</b>. ACL2 doesn't know <b>simple arithmetic</b> that can simplify the
 term @('(+ 1 -1 x)').  <b>A</b>.  You should load an arithmetic book whenever
 you're dealing with an arithmetic problem.  The simplest arithmetic book is
 typically loaded with the event @('(include-book "arithmetic/top-with-meta"
 :dir :system)').  If you're using @('floor') and @('mod') or non-linear
 arithmetic like @('(* x y)') you should use @('(include-book
 "arithmetic-5/top" :dir :system)').  See also the discussion of arithmetic
 books under the ``Lemma Libraries and Utilities'' link of the ACL2 home page,
 and see @(see community-books).</p>

 <p><b>Q</b>. ACL2 is not using an <b>arithmetic lemma</b> that I proved.
 <b>A</b>. Lemmas concluding with arithmetic inequalities, like</p>

 @({
  (implies (member e x)
           (< (len (delete e x)) (len x)))
 })

 <p>are not good rewrite rules because they rarely match targets because of
 intervening arithmetic operators.  For example, the above conclusion doesn't
 match @('(< (LEN (DELETE E X)) (+ 1 (LEN X)))').  You should store such lemmas
 as @(':linear') rules by using the command:</p>

 @({
  (defthm len-delete
    (implies (member e x)
             (< (len (delete e x)) (len x)))
    :rule-classes :linear)
 })

 <p>See @(see linear).</p>

 <p><b>Q</b>.  What is a <b>linear rule</b>?  <b>A</b>.  See @(see linear).</p>

 <p><b>Q</b>. How do I make ACL2 <b>treat a relation as an equality</b>?
 <b>A</b>. We assume you mean to treat the relation as an equivalence, i.e.,
 replace one term by another when they are equivalent under your relation.  See
 @(see equivalence), see @(see congruence), and see @(see refinement).</p>

 <p><b>Q</b>. One of my rewrite rules has a <b>hypothesis that doesn't
 rewrite</b> to true.  What do I do?  <b>A</b>. Prove a rewrite rule that
 establishes that hypothesis under the relevant assumptions from the context of
 the intended target.  Alternatively, undo the rule and restate it with a
 @(tsee force) around the problematic hypothesis, making ACL2 assume the
 hypothesis when the rule is applied and raising the truth of the hypothesis as
 an explicit subgoal of the proof.  See also @(tsee case-split).  Of course,
 you should always state the strongest rewrite rules you can think of,
 eliminating hypotheses or shifting them to the right-hand side inside of
 @('IF')s; see @(see strong-rewrite-rules).</p>

 <p><b>Q</b>. How do I make ACL2 ``guess'' the <b>right instantiation of a free
 variable</b>?  <b>A</b>. You can provide a @(':restrict') hint that names the
 problematic lemma and provides an instantiation of the free variable.  See
 @(see hints), specifically @(':restrict').  You could alternatively give a
 hint that @(':uses') the rule and provides the appropriate instantiation in
 full.  See @(see hints), specifically @(':use').  Recall that ACL2 guesses
 free variable instantiations by matching the problematic hypothesis to the
 assumptions in the context of the target.  If the appropriate assumption is
 present but ACL2 is finding another one, try undoing the problematic rule and
 proving it again, specifying the @(':match-free :all') modifier of the
 @(':rewrite') or @(':linear') rule class.  See @(see rule-classes).
 Alternatively, undo and prove the problematic rule again and use a @(tsee
 bind-free) form to compute the appropriate instantiation.</p>

 <p><b>Q</b>. How can I make ACL2 do a <b>case split</b> to prove a certain
 subgoal?  <b>A</b>. See @(see hints), specifically @(':cases').</p>

 <p><b>Q</b>. How can I <b>prevent ACL2 from using a rewrite rule</b>?
 <b>A</b>.  See @(see hints), specifically @(':in-theory (disable ...)').  If
 the use of the rule is problematic in only one subgoal and the lemma is needed
 in other subgoals, disable the lemma only in the problematic subgoal by
 specifying the subgoal name (e.g., @('"Subgoal 1/3.2.1"')) as the goal
 specifier in the hint.  If the rule isn't needed anywhere in the proof, you
 could use the specifier @('"Goal"').  If you don't think the rule will ever
 be needed for a while, you could globally disable it with the event
 @('(in-theory (disable ...))')  (see @(see in-theory)) executed before the
 first problematic proof.  If the rule has never been used or must always be
 disabled, undo it and prove it again with @(':')@(tsee rule-classes)
 @('nil').</p>

 <p><b>Q</b>.  How can I prevent ACL2 from running a definition on constants?
 I tried disabling the function but that didn't work.  <b>A</b>.  If you have a
 function named @('f') then disabling @('f') will disable the definitional
 axiom about @('f').  But ACL2 has another kind of rule about @('f'), telling
 it how to evaluate @('f').  The @(see rune) of this rule is
 @('(:executable-counterpart f)').  Try disabling that, as in the @(':')@(tsee
 hints) @('((')...  @(':in-theory (disable (:executable-counterpart f))
 ...c[))').</p>

 <p><b>Q</b>. How can I make ACL2 <b>use a rule</b> in a proof?  <b>A</b>. See
 @(see hints), specifically @(':use').</p>

 <p><b>Q</b>.  How can I make ACL2 expand a function call in a proof?
 <b>A</b>.  You can give an @(':')See @(see expand) hint.</p>

 <p><b>Q</b>.  ACL2 sometimes aborts the proof attempt before showing me all of
 the subgoals.  How can I make it just keep going instead of aborting early?
 <b>A</b>. See @(see otf-flg), which stands for Onward Thru the Fog FLaG.</p>

 <p><b>Q</b>. How can I <b>compute when I want a rule to fire</b>?  <b>A</b>.
 See @(see syntaxp).</p>

 <p><b>Q</b>.  How can I add <b>pragmatic advice to a lemma after it has been
 proved</b>?  For example, how can add a forced hypothesis, a backchain limit,
 or a @('syntaxp') test?  <b>A</b>.  You can't.  You can undo the lemma,
 restate it appropriately, and prove it again.  This produces the cleanest
 database.  Alternatively, you can prove the restated lemma under a new name
 &mdash; a task that should be easy since the old version is in the database
 and will presumably make the proof trivial &mdash; and then disable the old
 name.</p>

 <p><b>Q</b>. How can I <b>stop ACL2 from rewriting a term</b>?  <b>A</b>. If
 you need rewriting done but want to prevent some particular terms from being
 rewritten, see @(see hints), specifically @(':hands-off').  Alternatively,
 consider embedding the problematic term in a @(tsee hide).  Users sometime
 develop special theories (see @(see theory)) containing just the rules they
 want and then use hints to switch to those theories on the appropriate
 subgoals.</p>

 <p><b>Q</b>.  Can I <b>compute which subgoals a hint refers to</b>?  <b>A</b>.
 Yes, see @(see computed-hints).  This topic is for advanced users but knowing
 that it is possible might come in handy someday.</p>

 <p><b>Q</b>.  I want the rewriter to <b>always use one theory and then switch
 to another</b> so that it doesn't use my most complicated before until doing
 the simple things.  <b>A</b>.  This is possible but is something for the
 advanced user.  It can be done using a form of @(see computed-hints).  See
 @(see using-computed-hints-7).</p>

 <p><b>Q</b>.  Is there a way to attach <b>the same hint to every defthm</b>?
 <b>A</b>.  See @(see default-hints).</p>

 <p><b>Q</b>.  How can I just tell ACL2 the proof steps?  <b>A</b>.  See @(see
 verify) and see @(see proof-builder).</p>

 <p><b>Q</b>. How can I write <b>my own simplifier</b>?  <b>A</b>.  See @(see
 meta).</p>

 <p><b>Q</b>. How can I add an axiom or just assume some lemma without proof?
 <b>A</b>. This is very dangerous but is a good strategy for exploring whether
 or not a certain set of lemmas (and their rules) is sufficient to prove your
 goal.  See @(see defaxiom) and see @(see skip-proofs).</p>

 <p><b>Q</b>. How can redefine a user-defined function?  <b>A</b>.  This is
 tricky.  What if you've already proved theorems about the old definition and
 then wish to change it?  There are several options.  See @(see
 ld-redefinition-action) (and note specifically the discussion of updater
 function for it, @('set-ld-redefinition-action')); also see @(see redef), see
 @(see redef!), see @(see redef+), and see @(see redef-).</p>

 <p><b>Q</b>. How do I <b>change a function from</b> @(':program') <b>mode
 to</b> @(':logic') <b>mode</b>?  <b>A</b>. See @(see verify-termination).</p>

 <p><b>Q</b>. How do I <b>change the guards</b> on a function?  <b>A</b>. You
 can't.  Undo it and redefine it.</p>

 <p><b>Q</b>. What is <b>program mode</b>?  <b>A</b>. See @(see program).</p>

 <p><b>Q</b>. What does the ACL2 <b>prompt</b> mean?  <b>A</b>.  See @(see
 introduction-to-a-few-system-considerations) or, specifically, see @(see
 prompt).</p>

 <p><b>Q</b>. What is <b>logic mode</b>?  <b>A</b>. See @(see logic).</p>

 <p><b>Q</b>. How do I <b>get into or out of</b> @(':program') <b>mode?</b>
 @(':Logic') <b>mode?</b> <b>A</b>. See @(see program) and see @(see logic).
 You can enter these modes temporarily for a particular @(tsee defun) by using
 @('(declare (xargs :mode :program))') or @('(declare (xargs :mode :logic))')
 after the list of formal parameters to the definition.</p>

 <p><b>Q</b>.  How do I quit from ACL2?  <b>A</b>.  This varies depending on
 the interface you're using.  See @(see
 introduction-to-a-few-system-considerations).</p>

 <p><b>Q</b>. How do I <b>load a file</b> of definitions and theorems created
 by someone else?  <b>A</b>. See @(see include-book).</p>

 <p><b>Q</b>. How do I <b>create my own book</b> of definitions and theorems?
 <b>A</b>. See @(see books).</p>

 <p><b>Q</b>. Where are the books referenced by <b>:dir :system</b> on my
 machine?  <b>A</b>. If your ACL2 is installed on the directory
 <i>dir</i>@('/acl2-sources') and you follow the standard @(see installation)
 instructions, then the books are typically the files under the directory
 <i>dir</i>@('/acl2-sources/books/').</p>

 <p><b>Q</b>. How can I find out <b>what books are available</b>?  <b>A</b>. Go
 to the ACL2 home page, @('http://www.cs.utexas.edu/u/moore/acl2/') and look at
 the link labeled ``Lemma Libraries and Utilities.''</p>

 <p><b>Q</b>. How do I <b>produce my own book</b>?  <b>A</b>. See @(see
 books).</p>

 <p><b>Q</b>. What is a <b>decision procedure</b>?  What <b>decision procedures
 does ACL2 have</b>?  <b>A</b>. A <i>decision procedure</i> is an algorithm
 that given enough time and space can determine, for all the formulas in a
 certain syntactic class of formulas, whether the formula is a theorem or not.
 The most well-known decision procedure is for propositional calculus: by
 testing a formula under all the combinations Boolean assignments to the
 variables, one can decide if a propositional formula is a theorem.  The
 syntactic class consists of all formulas you can write using just variables,
 constants, and compositions of the functions @('and'), @('or'), @('not'),
 @('implies'), @('iff'), and @('if').  There are, of course, an exponential
 number of different assignments so the algorithm can be slow.  ACL2 contains a
 propositional decision procedure based on symbolic normalization that can be
 faster than trying all the combinations of truth values &mdash; but is not
 guaranteed to be faster.  ACL2 also contains an optional @(see bdd) procedure.
 ACL2 also contains a decision procedure for rational arithmetic involving
 variables, rational constants, addition, multiplication by rational constants,
 equality, and the various versions of arithmetic inequality (@('<'), @('<='),
 @('>='), and @('>')).  It can be extended with @(':')@(tsee linear) lemmas.
 ACL2 is complete for equality over uninterpreted (e.g., undefined and
 unconstrained) function symbols using an algorithm based on transitive closure
 of equivalence classes under functional substitutivity.  Finally, you can make
 ACL2 use other decision procedures, even ones implemented outside of ACL2; see
 @(see clause-processor).</p>

 <p><b>Q</b>. ACL2 has the <b>change of variable</b> trick (<b>destructor
 elimination</b>) that it does to get rid of @('(CAR X)') and @('(CDR X)') by
 replacing @('x') by @('(CONS A B)').  Is there a way to make ACL2 do that for
 other terms?  <b>A</b>. Yes.  See @(see elim).</p>

 <p><b>Q</b>. How can I <b>prevent destructor elimination</b>?  <b>A</b>. See
 @(see hints), specifically @(':do-not '(eliminate-destructors)').</p>

 <p><b>Q</b>. How can I <b>prevent cross-fertilization</b>?  <b>A</b>. See
 @(see hints), specifically @(':do-not '(fertilize)').</p>

 <p><b>Q</b>. How can I <b>prevent generalization</b>?  <b>A</b>. See @(see
 hints), specifically @(':do-not '(generalize)').</p>

 <p><b>Q</b>. How can I make ACL2 <b>impose a restriction on a new variable</b>
 introduced by destructor elimination or generalization?  <b>A</b>.  See @(see
 generalize).</p>

 <p><b>Q</b>. What <b>rule classes</b> are there?  <b>A</b>. See @(see
 rule-classes).</p>

 <p><b>Q</b>. What is a <b>theory</b>?  <b>A</b>. See @(see theories).</p>

 <p><b>Q</b>. How are <b>hints inherited by the children of a subgoal</b>?
 <b>A</b>. See @(see hints-and-the-waterfall).</p>

 <p><b>Q</b>.  How do I use ACL2 under <b>Emacs</b>?  <b>A</b>. See @(see
 emacs).</p>

 <p><b>Q</b>.  How do I use ACL2 under <b>Eclipse</b>?  <b>A</b>. See @(see
 ACL2-Sedan).</p>

 <p><b>Q</b>.  How do I interrupt the prover?  <b>A</b>.  The keyboard sequence
 for interrupting a running process depends your operating system, host Common
 Lisp, and user interface (e.g., Emacs, Eclipse, etc.).  But perhaps a few
 examples will help you discover what you need to know.  If your host Common
 Lisp is GCL or Allegro and you are typing directly to the Common Lisp process,
 then you can interrupt a computation by typing ``ctrl-c'' (hold down the
 Control key and hit the ``c'' key once).  But other Lisps may require some
 other control sequence.  If you are typing to an Emacs process which is
 running the GCL or Allegro Common Lisp process in a shell buffer, you should
 type ctrl-c ctrl-c &mdash; that is, you have to type the previously mentioned
 sequence twice in succession.  If you are running the ACL2 Sedan, you can use
 the <i>Interrupt Session</i> button on the tool bar.  The environment you
 enter when you interrupt depends on various factors and basically you should
 endeavor to get back to the top level ACL2 command loop, perhaps by typing
 some kind of Lisp dependent ``abort'' command like @(':q') or @(':a').  You
 can usually determine what environment you're in by paying attention to the
 prompt.</p>

 <p><b>Q</b>.  What is the <b>ACL2 loop</b>?  <b>A</b>.  That is the name given
 to the interactive environment ACL2 provides, a ``read-eval-print loop'' in
 which the user submits successive commands by typing ACL2 expressions and
 keyword commands.  See @(see introduction-to-a-few-system-considerations).</p>

 <p><b>Q</b>.  What is <b>raw lisp</b>?  <b>A</b>.  That is our name for the
 host Common Lisp in which ACL2 is implemented.  See @(see
 introduction-to-a-few-system-considerations).  There is an ACL2 mode named
 <i>raw mode</i> which is different from ``raw lisp.''  See @(see
 set-raw-mode).</p>

 <p><b>Q</b>.  Can I get a tree-like view of a proof?  <b>A</b>.  See @(see
 proof-tree) for an Emacs utility that displays proof trees and allows you to
 navigate through a proof from the proof tree.  The ACL2 Sedan also supports
 proof trees and you should see the ACL2s documentation on that topic.</p>

 <p><b>Q</b>.  I used the earlier Boyer-Moore theorem prover, Nqthm.  How is
 ACL2 different?  <b>A</b>. See @(see nqthm-to-acl2).</p>

 <p>If you are reading this as part of the tutorial introduction to the theorem
 prover, use your browser's <b>Back Button</b> now to return to @(see
 introduction-to-the-theorem-prover).</p>")

(defxdoc full-book-name
  :parents (books-reference)
  :short "Book naming conventions assumed by ACL2"
  :long "<p>See @(see pathname) for background on ACL2 pathnames.</p>

 <p>ACL2 defines a ``full-book-name'' to represent an absolute filename of a
 book.  This is typically a ``full-book-name string'' or simply
 ``full-book-string'': an absolute filename for the book.  At the end of this
 topic we mention a second representation, the <i>@(see sysfile)</i>; but until
 then, our discussion of full-book-names is restricted to the special (but
 common) case of full-book-strings.</p>

 <p>A full-book-name string may be divided into contiguous sections: a
 ``directory string'', a ``familiar name'' and an ``extension''.  See @(see
 pathname) for the definitions of ``absolute,'' ``filename string,'' and other
 notions pertaining to naming files.  Below we exhibit the three sections of
 one such string:</p>

 @({
  "/usr/home/smith/project/arith.lisp"

  "/usr/home/smith/project/"           ; directory string
                          "arith"      ; familiar name
                               ".lisp" ; extension
 })

 <p>The sections are marked by the rightmost slash and rightmost dot, as shown
 below.</p>

 @({
  "/usr/home/smith/project/arith.lisp"
                          |     |
                          slash dot
                          |     |
  "/usr/home/smith/project/"           ; directory string
                          "arith"      ; familiar name
                               ".lisp" ; extension
 })

 <p>The directory string includes (and terminates with) the rightmost slash.
 The extension includes (and starts with) the rightmost dot.  The dot must be
 strictly to the right of the slash so that the familiar name is well-defined
 and nonempty.</p>

 <p>We conclude by discussing the other representation of full-book-names as
 promised above: the sysfile, which is a pair of the form @('(:kwd
 . "relpath")') where @(':kwd') is a @(see keyword) and @('"relpath"') is a
 relative pathname string.  See @(see sysfile) for a discussion of sysfiles.
 Here, we simply remark that sysfiles are used primarily by the implementation;
 as an ACL2 user you might never see one.  Sysfiles are used for
 full-book-names in @(see certificate) files and in various data structures in
 the ACL2 logical @(see world).</p>")

(defxdoc function-theory
  :parents (theories theory-functions)
  :short "Function symbol rules as of logical name"
  :long "@({
  Examples:
  (function-theory :here)
  (function-theory 'lemma3)
 })

 <p>See @(see logical-name).</p>

 @({
  General Form:
  (function-theory logical-name)
 })

 <p>Returns the theory containing all the @(':')@(tsee definition) @(see
 rune)s, whether @(see enable)d or not, that existed immediately after @(tsee
 logical-name) was introduced.  See the documentation for @(see theories),
 @(see logical-name) and @(tsee executable-counterpart-theory).</p>

 <p>You may experience a fencepost problem in deciding which logical name to
 use.  @(tsee Deflabel) can always be used to mark unambiguously for future
 reference a particular point in the development of your theory.  The order of
 @(see events) in the vicinity of an @(tsee encapsulate) is confusing.  See
 @(see encapsulate).</p>

 <p>This ``function'' is actually a macro that expands to a term mentioning the
 single free variable @(tsee world).  When theory expressions are evaluated by
 @(tsee in-theory) or the @(':')@(tsee in-theory) hint, @(tsee world) is bound
 to the current ACL2 @(see world).</p>")

(defxdoc functional-instantiation
  :parents (encapsulate)
  :short "An analogue in ACL2 of higher-order logical reasoning.  Functional
 instantiation allows you to prove theorems ``by analogy'' with previous
 theorems.  See @(see hints) and see @(see lemma-instance).")

(defxdoc functional-instantiation-example
  :parents (functional-instantiation tutorial5-miscellaneous-examples)
  :short "A small proof demonstrating functional instantiation"
  :long "<p>The example below demonstrates the use of functional instantiation,
 that is, the use of a generic result in proving a result about specific
 functions.  In this example we constrain a function to be associative and
 commutative, with an identity or ``root,'' on a given domain.  Next, we define
 a corresponding function that applies the constrained associative-commutative
 function to successive elements of a list.  We then prove that the latter
 function gives the same value when we first reverse the elements of the list.
 Finally, we use functional instantiation to derive the corresponding result
 for the function that multiplies successive elements of a list.</p>

 <p>The details of the proof (such as the @(tsee in-theory) event and
 particulars of the lemmas) are not the point here.  Rather, the point is to
 demonstrate the interaction of @(tsee encapsulate) @(see events) and
 @(':functional-instance') @(see lemma-instance)s.  Of course, if you are
 interested in details then you may find it helpful to run these @(see events)
 through ACL2.</p>

 <p>Also see @(see constraint) for more about @(':functional-instance') and see
 @(see lemma-instance) for general information about the use of
 previously-proved lemmas.  It may also be helpful to see @(tsee
 set-constraint-tracking) or to run the script below after doing
 @('(set-constraint-tracking t)').</p>

 @({
  (in-package "ACL2")

  (encapsulate
   (((ac-fn * *) => *)
    ((ac-fn-domain *) => *)
    ((ac-fn-root) => *))
   (local (defun ac-fn (x y) (+ x y)))
   (local (defun ac-fn-root () 0))
   (local (defun ac-fn-domain (x) (acl2-numberp x)))
   (defthm ac-fn-comm
     (equal (ac-fn x y)
            (ac-fn y x)))
   (defthm ac-fn-assoc
     (equal (ac-fn (ac-fn x y) z)
            (ac-fn x (ac-fn y z))))
   (defthm ac-fn-id
     (implies (ac-fn-domain x)
              (equal (ac-fn (ac-fn-root) x)
                     x)))
   (defthm ac-fn-closed
     (and (ac-fn-domain (ac-fn x y))
          (ac-fn-domain (ac-fn-root)))))

  ;;;;;;;;;;;;;;;;;;;;;;;
  ; End of encapsulate. ;
  ;;;;;;;;;;;;;;;;;;;;;;;

  ; Define a ``fold'' function that iteratively applies ac-fn over a list.
  (defun ac-fn-list (x)
    (if (atom x)
        (ac-fn-root)
      (ac-fn (car x)
             (ac-fn-list (cdr x)))))

  ; Recognize lists all of whose elements are in the intended domain.
  (defun ac-fn-domain-list (x)
    (if (atom x)
        t
      (and (ac-fn-domain (car x))
           (ac-fn-domain-list (cdr x)))))

  ; Define a list reverse function.
  (defun rev (x)
    (if (atom x)
        nil
      (append (rev (cdr x))
              (list (car x)))))

  ; The following is needed for proving ac-fn-list-append, which is
  ; needed for proving ac-fn-list-rev.
  (defthm ac-fn-list-closed
     (ac-fn-domain (ac-fn-list x)))

  ; Needed for proving ac-fn-list-rev:
  (defthm ac-fn-list-append
    (implies (and (ac-fn-domain-list x)
                  (ac-fn-domain-list y))
             (equal (ac-fn-list (append x y))
                    (ac-fn (ac-fn-list x)
                           (ac-fn-list y)))))

  ; Needed for proving ac-fn-list-rev:
  (defthm ac-fn-domain-list-rev
    (equal (ac-fn-domain-list (rev x))
           (ac-fn-domain-list x)))

  ; The following is a good idea because without it, the proof attempt
  ; for ac-fn-list-rev (see just below) fails with the term (HIDE
  ; (AC-FN-LIST NIL)).  It is often a good idea to disable
  ; executable-counterparts of functions that call constrained
  ; functions.
  (in-theory (disable (:executable-counterpart ac-fn-list)))

  (defthm ac-fn-list-rev
    (implies (ac-fn-domain-list x)
             (equal (ac-fn-list (rev x))
                    (ac-fn-list x))))

  ; Our goal now is to apply functional instantiation to ac-fn-list-rev
  ; in order to prove the corresponding theorem, times-list-rev, based
  ; on * instead of ac-fn.

  (defun times-list (x)
    (if (atom x)
        1
      (* (car x)
         (times-list (cdr x)))))

  (defun number-listp (x)
    (if (atom x)
        t
      (and (acl2-numberp (car x))
           (number-listp (cdr x)))))

  ; The following relies on the following built-in rules for * (whose
  ; statements correspond directly to their names): commutativity-of-*,
  ; associativity-of-*, and unicity-of-1.

  (defthm times-list-rev
    (implies (number-listp x)
             (equal (times-list (rev x))
                    (times-list x)))
    :hints (("Goal"
             :use
             ((:functional-instance
               ac-fn-list-rev
               ;; Instantiate the generic functions:
               (ac-fn *)
               (ac-fn-root (lambda () 1))
               (ac-fn-domain acl2-numberp)
               ;; Instantiate the other relevant functions:
               (ac-fn-list times-list)
               (ac-fn-domain-list number-listp))))))
 })")

(defxdoc functional-instantiation-in-acl2r
  :parents (functional-instantiation)
  :short "Additional requirements for @(':functional-instance') hints in
  ACL2(r)"
  :long "<p>This documentation topic relates to ACL2(r), the modification of
 ACL2 that supports the real numbers (see @(see real)).</p>

 <p>See @(see hints) and see @(see lemma-instance) for a discussion of
 @(':use') hints that employ the @(':functional-instance') keyword.  Here, we
 document additional requirements for such hints that applies to ACL2(r).  We
 assume familiarity with lemma instances; see @(see lemma-instance).</p>

 <p>(1) When functionally instantiating a non-classical formula, it is illegal
 to use pseudo-lambda expressions in a lemma instance.</p>

 <p>(2) A classical function symbol must be bound either to a classical
 function symbol or to a lambda (or, if allowed, pseudo-lambda) expression with
 a classical body.  Similarly, a non-classical function symbol must be bound
 either to a non-classical function symbol or to a lambda (or, if allowed,
 pseudo-lambda) expression with a non-classical body.</p>")

(defxdoc further-information-on-rewriting
  :parents (introduction-to-the-theorem-prover)
  :short "A grab bag of advice and information on rewriting"
  :long "<p>In the following paragraphs we give some links to advanced topics,
 marked with ``<see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>''.  If you are reading this topic as part of the
 tutorial on the theorem prover, do not follow these links upon your first
 reading.  Just take note of the existence of the facilities and ideas
 mentioned.</p>

 <p>@(see Arithmetic): If your goal theorem involves even trivial arithmetic,
 such as adding or subtracting @('1'), we recommend that you do</p>

 @({
  (include-book "arithmetic/top-with-meta" :dir :system)
 })

 <p>which loads into ACL2 all the rules in one of the so-called ACL2
 ``community books'' (see @(see community-books)).  (<i>Books</i> are certified
 files of definitions, lemmas, etc., usually prepared by other ACL2 users and
 explicitly shared with the community.  The ACL2 @(see installation)
 instructions suggest downloading the community books.)  The book
 "top-with-meta" is the most elementary and most widely used arithmetic book.
 Other community books include "arithmetic-5/top" and various hardware and
 floating-point arithmetic books; if including "arithmetic/top-with-meta"
 isn't sufficient, you could try @('(include-book
 "arithmetic-5/top" :dir :system)').</p>

 <p><b>Rules Concluding with Arithmetic Inequalities</b>: If you are tempted to
 create a rewrite rule with an arithmetic inequality as its conclusion or
 left-hand side, think again.  Inequalities such as</p>

 @({
  (<= (len (delete e x)) (len x))
 })

 <p>make poor left-hand sides for rewrite rules.  For example, the inequality
 above does not match the target</p>

 @({
  (<= (LEN (DELETE E X)) (+ 1 (LEN X)))
 })

 <p>even though it is sufficient to prove the target (given some simple
 arithmetic).  We recommend that if you have a theorem that establishes an
 arithmetic inequality, you make it a <i>linear</i> rule.  See @(see linear)
 <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>.</p>

 <p><b>Rearranging Formulas Before Making Rules</b>: It is possible to
 rearrange the propositional structure of a proved formula before processing it
 as a rule.  This allows you to state a theorem one way ``for publication'' and
 rearrange it to be stored as a more effective rule.  See @(see
 introduction-to-the-database) (a tutorial topic you'll come to later) and its
 discussion of the concept of @('corollary').  Also, see the discussion of
 @('corollary') in @(tsee rule-classes) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>.</p>

 <p><b>Rewriting with New Equivalence Relations</b>: You may introduce new
 <i>equivalence</i> relations, like ``set-equal'' or ``is-a-permutation'' and
 cause the rewriter to replace equivalents by equivalents in suitable contexts,
 where you use <i>congruence</i> rules to inform ACL2 of where these more
 relaxed notions of equivalence may be used; see @(see equivalence) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see> and
 see @(see congruence) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>.</p>

 <p><b>Pragmatic Advice to Control Rules</b>: You may attach various
 <i>pragmas</i> to a rule that allow you rather fine heuristic control over
 whether and how the rule is applied.  For example, you may mark a hypothesis
 to be <i>forced</i> (see @(see force) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>)
 meaning that the rule is to be applied even if that hypothesis is not relieved
 &mdash; but if the proof is successful the system will turn its attention to
 all forced subgoals.  You may similarly mark a hypothesis so as to cause a
 case split, allowing the relief of the hypothesis on one branch and spawning
 another branch explicitly denying the hypothesis; see @(see case-split) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>.
 You may add a bogus hypothesis that looks at the intended application of the
 rule and decides whether to apply the rule or not, performing an arbitrary
 computation on the syntactic context of the application; see @(see syntaxp)
 <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>.  By providing a @(':match-free') modifier to the
 @(':rewrite') rule declaration in your rule-classes, you may tell ACL2 to try
 all or only the first free variable value it guesses (see @(see rule-classes)
 <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>).  You may provide a bogus hypothesis that computes
 from the syntactic environment the values to guess for the free variables in a
 rule; see @(see bind-free) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>.
 You may mark a term so that the rewriter does not dive into it; see @(see
 hide) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>.</p>

 <p><b>Programming Your Own Rewriter</b>: If you cannot find a way to use
 rewrite rules to make the transformations you desire, you might investigate
 the use of <i>metafunctions</i>.  A metafunction is just a little theorem
 prover of your own design.  It takes as input a list structure representing a
 term and returns a list structure representing a term.  If you can prove that
 the meaning of the input and output terms are equivalent, you can extend the
 ACL2 simplifier to call your metafunction.  See @(see meta) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>.</p>

 <p><b>The Order in which Targets are Rewritten</b>: The rewriter sweeps
 through terms ``inside-out'' otherwise known as ``left-most innermost first''.
 Thus, before trying to apply rewrite rules to @('(')<i>f a1 ... an</i>@(')'),
 rules are applied to the <i>ai</i>.  This has the good effect of normalizing
 the <i>ai</i>.</p>

 <p>This fact might help you understand why sometimes your rules ``don't seem
 to fire.''  For example, suppose you have a rule for rewriting @('(len (rev
 x))') to @('(len x)') and suppose you wish to prove a theorem about @('(LEN
 (REV (CONS A B)))').  Suppose @('rev') is defined in terms of @('append'), as
 shown in @(see programming-knowledge-taken-for-granted).  Then you might see a
 checkpoint in which the @('(LEN (REV ...))') above has been simplified to
 @('(LEN (APPEND (REV B) (LIST A)))') instead of to @('(LEN (CONS A B))').  Why
 wasn't your rule about @('(len (rev x))') applied?  The reason is that @('(REV
 (CONS A B))') rewrote to @('(APPEND (REV B) (LIST A))') before rules were
 applied to @('(LEN (REV ...))').  You need a rule about @('(len (append x
 y))'), as you will see from the checkpoint.</p>

 <p><b>The Order in which Rules are Tried</b>: The rewriter tries the most
 recently proved rules first.  For example, suppose @('f'), @('g'), and @('h')
 are functions defined so that the following two theorems are provable and
 suppose you executed the following two events in the order shown:</p>

 @({
  (defthm rule1 (equal (f (g x)) (h 1 x)))
  (defthm rule2 (equal (f (g x)) (h 2 X)))
 })

 <p>Then if rewrite rules are applied to @('(F (G A))'), the result will be
 @('(H 2 A)'), because the latter rule, @('rule2'), is applied first.  It is
 generally best not to have conflicting rules or, at least, to understand how
 such conflicts are resolved.  The system will warn you when you propose a rule
 that conflicts with an existing one.</p>

 <p>If you were reading this topic as part of the tutorial introduction to the
 theorem prover, use your browser's <b>Back Button</b> now to return to @(see
 introduction-to-rewrite-rules-part-2).</p>")

(defxdoc future-work-related-to-the-tau-system
  :parents (introduction-to-the-tau-system)
  :short "Some tau system problems that we hope someone will address"
  :long "<p>The tau system is inexpressive compared to modern polymorphic type
 systems &mdash; something that may be unavoidable in an untyped first-order
 language.  However, we believe its effectiveness could be greatly increased by
 the development of some additional tools.  We also believe that most of these
 tools could be provided by ACL2 users creating certified community books that
 exploit the basic tools already provided.  It is likely the initial attempts
 to create such books will show the inadequacy of some of the current
 algorithms and data structures in the tau system and might point the way to
 improvements.</p>

 <p>As implementors of ACL2 our preference is to support the improvement of the
 core algorithms and data structures and provide customizable hooks allowing
 users to exploit them by developing effective and convenient interfaces.
 However, we want the further elaboration and optimization of the tau system to
 be based on user experience not just speculation.</p>

 <p>Some tools we <i>think</i> might help are listed below.  We invite
 volunteers and further suggestions.</p>

 <p><i>A tau-centric signature notation</i> for use in function definitions,
 exploited by a macro replacing @('defun') so that input-output relationships
 phrased in tau terms are proved as @(':tau-system') rules immediately after
 functions are introduced:</p>

 <p>We have, for example, experimented with a book defining a macro that allows
 the definition of the function @('ap') (append) accompanied by a signature
 rule.  Subsequent @('defsig') events can add other signatures in the same
 notation.</p>

 @({
  (defsig ap (true-listp * true-listp ==> true-listp) (x y)
     (if (consp x)
         (cons (car x) (ap (cdr x) y))
         y))

  (defsig ap (integer-listp * integer-listp ==> integer-listp))
 })

 <p>This experimental book provides succinct syntax for all tau signatures.
 For example, that book parses the signature</p>

 @({
  (NATP (/= 3 5 7) (< 16) * TRUE-LISTP ==> BOOLEANP * INTEGER-LISTP * NATP)
 })

 <p>to be the signature of a function with two inputs and three outputs.  The
 first input must be a natural number, different from 3, 5, and 7, and less
 than 16.  The second input must be a true list.  The first output is a
 boolean, the second a list of integers, and the third a natural.</p>

 <p>To express this signature for function @('fn') as a formula requires
 significantly more typing by the user:</p>

 @({
  (IMPLIES (AND (NATP X)
                (NOT (EQUAL X 3))
                (NOT (EQUAL X 5))
                (NOT (EQUAL X 7))
                (< X 16)
                (TRUE-LISTP Y))
           (AND (BOOLEANP (MV-NTH 0 (FN X Y)))
                (INTEGER-LISP (MV-NTH 1 (FN X Y)))
                (NATP (MV-NTH 2 (FN X Y)))))
 })

 <p>We suspect that the provision of some succinct tau-centric notation (not
 necessarily the one above) for signatures at definition-time will mean users
 get more benefit from the tau system.</p>

 <p><i>Some tau inference mechanisms</i>: This phrase suggests two different
 improvements.  One is to implement a mechanism that adds or completes
 signatures for function definitions by exploiting knowledge of commonly used
 recursive schemas and the signatures of the subroutines in the body.  For
 example, the definition of @('ap') above rather obviously has the
 signature</p>

 @({
  (integer-listp * integer-listp ==> integer-listp)
 })

 <p>and many others just based on the two recursive schemas that (a) collect
 certain elements from lists and (b) check that all elements have a certain
 property.</p>

 <p>The other ``tau inference'' improvement is to implement a mechanism for
 inferring relations between user-defined Booleans, perhaps by exploiting
 example generation, testing, and knowledge of recursive schemas.  For example,
 it is fairly obvious that @(tsee symbol-alistp) implies @(tsee alistp).
 Making the user state these relations invites omissions that render the tau
 system very unpredictable.</p>

 <p><i>A tau assistant</i>: It would be useful to have a way to find out what
 tau rules are missing.  Given a term that the user believes should
 ``obviously'' have some tau (``type'') what rules might be added to make the
 tau algorithm compute that expected tau?  For example, if @('(g x)') is known
 to satisfy @('P') and @('(f x)') is known to satisfy @('R') when its argument
 satisfies @('S'):</p>

 @({
  g : T ==> P
  f : S ==> R
 })

 <p>then if the user asserts that @('(f (g x))') ``ought'' to have tau @('R'),
 one plausible suggestion is the simple tau rule that @('(P x)') implies @('(S
 x)').  Such assistance &mdash; while still confronting an undecidable problem
 &mdash; might be easier to implement within the tau framework than more
 generally in ACL2.  (Many users have wanted such an assistant to suggest
 lemmas for the rewriter.)</p>")

(defxdoc |Flawed Induction Candidates in App Example|
  :parents (|Pages Written Especially for the Tours|)
  :short "Flawed Induction Candidates in App Example"
  :long "<p>Induction on <b>a</b> is unflawed: every occurrence of <b>a</b> in
 the conjecture</p>

 <code>
 (equal (app (app <b>a</b> b) c)
        (app <b>a</b> (app b c)))
 </code>

 <p>is in a position being recursively decomposed!</p>

 <p>Now look at the occurrences of @('b').  The first (shown in <b>bold</b>
 below) is in a position that is held constant in the recursion of @('(app a
 b)').  It would be ``bad'' to induct on @('b') here.</p>

 <code>
 (equal (app (app a <b>b</b>) c)
        (app a (app b c)))
 </code>")

(defxdoc |Free Variables in Top-Level Input|
  :parents (|Pages Written Especially for the Tours|)
  :short "Free Variables in Top-Level Input"
  :long "<code>
 ACL2 !&gt;<b>(equal (app (app a b) c)</b>
               <b>(app a (app b c))))</b>

 ACL2 Error in TOP-LEVEL:  Global variables, such as C, B, and A, are
 not allowed. See :DOC ASSIGN and :DOC @@.

 </code>

 <p>ACL2 does not allow ``global variables'' in top-level input.  There is no
 ``top-level binding environment'' to give meaning to these variables.</p>

 <p>Thus, expressions involving no variables can generally be evaluated,</p>

 <code>
 ACL2 !&gt;<b>(equal (app (app '(1 2) '(3 4)) '(5 6))</b>
               <b>(app '(1 2) (app '(3 4) '(5 6))))</b>
 (1 2 3 4 5 6)
 </code>

 <p>but expressions containing variables cannot.</p>

 <p>There is an exception to this rule.  References to ``single-threaded
 objects'' may appear in top-level forms.  See @(see stobj) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>.  A
 single-threaded object is an ACL2 object, usually containing many fields,
 whose use is syntactically restricted so that it may be given as input only to
 certain functions and must be returned as output by certain functions.  These
 restrictions allow single- threaded objects to be efficiently manipulated.
 For example, only a single copy of the object actually exists, even though
 from a logical perspective one might expect the object to be ``copied on
 write.''</p>

 <p>The most commonly used single-threaded object in ACL2 is the ACL2 system
 state, whose current value is always held in the variable @(tsee state) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>.</p>

 <p>ACL2 provides a way for you to use @('state') to save values of
 computations at the top-level and refer to them later.  See @(see assign) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see> and
 @(see @) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>.</p>")

(defxdoc |Functions for Manipulating these Objects|
  :parents (|Pages Written Especially for the Tours|)
  :short "Functions for Manipulating these Objects"
  :long "<p><see topic='@(url |Modeling in ACL2|)'><img
 src='res/tours/flying.gif'></img></see></p>

 <p>Consider a typical ``stack'' of control frames.</p>

 <p><img src='res/tours/stack.gif'></img></p>

 <p>Suppose the model required that we express the idea of ``the most recent
 frame whose return program counter points into @('MAIN').''</p>

 <p>The natural expression of this notion involves</p>

 <p><b>function application</b> &mdash; ``fetch the @('return-pc') of this
 frame''</p>

 <p><b>case analysis</b> &mdash; ``<b>if</b> the pc is @('MAIN'), <b>then</b>
 ...''</p>

 <p><b>iteration</b> or <b>recursion</b> &mdash; ``pop this frame off and
 repeat.''</p>

 <p>The designers of ACL2 have taken the position that a <b>programming</b>
 <b>language</b> is the natural language in which to define such notions,
 <b>provided</b> the language has a mathematical foundation so that models can
 be analyzed and properties derived logically.</p>

 <p>Common Lisp is the language supported by ACL2.  To be precise, a small
 applicative subset of Common Lisp is the language supported by ACL2.</p>

 <p><see topic='@(url |Modeling in ACL2|)'><img
 src='res/tours/flying.gif'></img></see></p>")

(defxdoc gag-mode
  :parents (output-controls)
  :short "Verbosity of proof output"
  :long "<p>Please see @(see set-gag-mode) for an explanation of gag-mode,
 which can take any of the following values:</p>

 @({
  (gag-mode) ; generally evaluates to t, nil, or :goals
 })")

(defxdoc gc$
  :parents (miscellaneous acl2-built-ins)
  :short "Invoke the garbage collector"
  :long "<p>This function is provided so that the user can call the garbage
 collector of the host Lisp from inside the ACL2 loop.  Specifically, a call of
 @('gc$') is translated into a call of a function below on the same
 arguments.</p>

 @({
  Allegro CL:            excl:gc
  CCL                    ccl::gc
  CLISP                  ext:gc
  CMU Common Lisp        system::gc
  GCL                    si::gbc [default argument list: (t)]
  LispWorks              hcl::gc-generation [default argument list:
                                             (7) for 64-bit OS, else (3)]
  SBCL                   sb-ext:gc
 })

 <p>The arguments, if any, are as documented in the underlying Common Lisp.  It
 is up to the user to pass in the right arguments, although we may do some
 rudimentary checks.</p>

 <p>Also see @(see gc-verbose).</p>

 <p>Evaluation of a call of this macro always returns @('nil').</p>

 <p>To include @('gc$') in a book, one can use @('value-triple'):</p>

 @({
 (value-triple (gc$))
 })")

(defxdoc gc-strategy
  :parents (miscellaneous acl2-built-ins)
  :short "The garbage collection strategy"
  :long "<p>The form @('(gc-strategy state)') provides the value the current
 garbage collection strategy if that notion is supported by the underlying host
 lisp (currently, CCL only).  The logical story is that @('gc-strategy') reads
 its value from the @('oracle') field of the ACL2 @(tsee 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 (see @(tsee read-acl2-oracle)) and the returned
 state has the updated (popped) acl2-oracle.</p>

 <p>For more information, see @(see set-gc-strategy).</p>")

(defxdoc gc-verbose
  :parents (gc$)
  :short "Control printing from the garbage collector"
  :long "@({
  General Form:
  (gc-verbose arg &optional arg2)
 })

 <p>Garbage collection (gc) is performed by every Lisp implementation; see
 @(see gc$).  However, different ACL2 builds might see more or fewer messages.
 This macro is intended to provide an interface for controlling the verbosity,
 which is off if the (first) argument evaluates to @('nil') and otherwise is
 on.  The second (optional) argument is currently ignored except when the host
 Common Lisp implementation is CCL, where it specifies verbosity for EGC.</p>

 <p>The above functionality is only supported for the following host Common
 Lisp implementations: CCL, CMUCL, and GCL.  Otherwise, the only effect of this
 macro is to print a notice that it is not supported.  You are welcome to
 contact the ACL2 developers if you would like to help in adding such support
 for another host Common Lisp.</p>

 <p>Evaluation of a call of this macro always returns @('nil').</p>")

(defxdoc gcl
  :parents (miscellaneous)
  :short "Tips on building and using ACL2 based on Gnu Common Lisp"
  :long "<p>See the @(see installation) instructions for basic information
 about building ACL2 on top of GCL, including information about where to fetch
 GCL.  Here, we provide some tips that may be useful.</p>

 <p>1. You can place forms to evaluate at start-up into file @('init.lsp') in
 the directory where you are starting ACL2 (GCL), or into file
 @('acl2-init.lsp') in your home directory.  For example, in order to evaluate
 both of the lisp forms mentioned in 2 below, you could put them both into
 @('init.lsp') in the current directory or in @('~/acl2-init.lsp') (either way,
 without @('(lp)') or @(':q')):</p>

 @({
  (setq si::*optimize-maximum-pages* nil)
  (si::allocate 'cons 75000 t)
 })

 <p>Note that if you want to put ACL2 patches in this file, you should precede
 them with (in-package "ACL2").</p>

 <p>2. Suppose you run out of space, for example with an error like this:</p>

 @({
     Error: The storage for CONS is exhausted.
       Currently, 59470 pages are allocated.
       Use ALLOCATE to expand the space.
 })

 <p>The following suggestion from Camm Maguire will minimize the heap size, at
 the cost of more garbage collection time.</p>

 @({
  :q   ; exit the ACL2 loop
  (setq si::*optimize-maximum-pages* nil)
  (lp) ; re-enter the ACL2 loop
 })

 <p>A second thing to try, suggested by several people, is to preallocate more
 pages before the run, e.g.:</p>

 @({
  :q   ; exit the ACL2 loop
  (si::allocate 'cons 75000 t)
  (lp) ; re-enter the ACL2 loop
 })

 <p>Also see @(see reset-kill-ring) for a suggestion on how to free up
 space.</p>

 <p>3. Windows users have seen this error:</p>

 @({
  cc1.exe: unrecognized option `-fno-zero-initialized-in-bss'
 })

 <p>Camm Maguire suggests that a solution may be to evaluate the following in
 GCL before building ACL2.</p>

 @({
  (in-package 'compiler)
  (let* ((x `-fno-zero-initialized-in-bss')
         (i (search x *cc*)))
          (setq *cc* (concatenate 'string
                                  (subseq *cc* 0 i)
                                  (subseq *cc* (+ i (length x))))))
 })

 <p>4. It is possible to profile using ACL2 built on GCL.  See file
 @('save-gprof.lsp') in the ACL2 source directory.</p>

 <p>5. Some versions of GCL may have garbage-collector bugs that, on rare
 occasions, cause ACL2 (when built on GCL) to break.  If you run into this, a
 solution may be to execute the following:</p>

 @({
  :q
  (si::sgc-on nil)
  (lp)
 })

 <p>Alternatively, put @('(si::sgc-on nil)') in your @('~/acl2-init.lsp')
 file.</p>

 <p>A full regression test and found that this decreased performance by about
 10%.  But even with that, GCL is probably one of the faster Common Lisp
 implementations for ACL2 on Linux.  Performance figures may often be found by
 following the ``Recent changes'' link on the ACL2 home page.</p>

 <p>6. GCL operations on numbers can sometimes be sped up, perhaps by up to two
 orders of magnitude, by suitable @(tsee declare) forms (also see @(see
 type-spec)).  The following example, developed with Warren Hunt and Serita
 Nelesen, illustrates the use of such declarations.  (This was some years ago,
 and the sizes of 28 and 29 can probably be increased now that Lisp
 implementations are 64-bit, with larger bounds on so-called fixnums.)</p>

 @({
  ; File iplus.lisp:
  ; Operations on naturals together with positive infinity (represented as -1).

  ; After (ld "iplus.lisp"), escape to raw Lisp with :q and then evaluate
  ; (disassemble 'big-test).  You should see lots of arithmetic operations
  ; in C code, but no calls of C functions CMPmake_fixnum or number_plus.

  (in-package "ACL2")

  (defmacro i-max ()
    (expt 2 (1- 28)))

  (defmacro i+ (x y)
    `(the (signed-byte 28)
          (let ((x ,x)
                (y ,y))
            (declare (type (signed-byte 28) x y))
            (cond ((or (< x 0)
                       (< y 0))
                   -1)
                  (t (let ((result
                            (the (signed-byte 29) (+ x y))))
                       (declare (type (signed-byte 29) result))
                       (cond ((>= result (i-max)) -1)
                             (t (the (signed-byte 28) result)))))))))

  (defmacro imin (x y)
    `(the (signed-byte 28)
          (let ((x ,x)
                (y ,y))
            (declare (type (signed-byte 28) x y))
            (cond ((< x 0)
                   (cond ((< y 0) -1)
                         (t y)))
                  ((< y 0)
                   x)
                  (t
                   (the (signed-byte 28) (min x y)))))))

  (defun big-test (x y z)
    (declare (type (signed-byte 28) x y z))
    (imin (i+ x y)
          (i+ y (imin x z))))
 })

 <p>7. You may want to set environment variable @('GCL_MEM_MULTIPLE') when
 running regression tests using ACL2 built on GCL, to keep memory from
 exceeding what is available.  Consider dividing 1.0 by the number of threads;
 so for example, for 4 threads (i.e., using &ldquo;@('-j 4')&rdquo; in your
 @('make') command), you may want to specify @('GCL_MEM_MULTIPLE=0.25').  But
 you can probably run with more threads (e.g., perhaps 20 threads or more on a
 64 MB machine) by instead doing a ``pooled memory run'', which may be
 performed as in the following example (bash syntax), as suggested by Camm
 Maguire.  Warning: the use of @('HOME') may change soon if it hasn't
 already.</p>

 @({
 HOME=/tmp ACL2=$(pwd)/saved_acl2 GCL_MULTIPROCESS_MEMORY_POOL=t \
   make -j 20 regression-fresh
 })

 <p>(Technical explanation: The reason for setting @('HOME') to directory
 @('/tmp') is to keep a so-called ``pool file'' local, since otherwise it will
 be on your home directory, which may be updated too infrequently if on a
 shared file system.)</p>")

(defxdoc geneqv
  :parents (introduction-to-the-theorem-prover break-rewrite)
  :short "the rewriter's generated equivalence relation"
  :long "<p>As the rewriter descends through a term, rewriting the subterms, it
  uses @(see congruence) rules to determine which @(see equivalence)s may be
  used to rewrite one subterm to another while ensuring that each rewrite
  maintains a given equivalence.  Generally speaking multiple equivalences may
  be used to rewrite subterms.  A ``generated equivalence'' or
  ``geneqv'' (pronounced ``genequiv'') is the way we encode which equivalences
  may be used by the rewriter at any given subterm position.</p>

  <p>The outline of this discussion is as follows.</p>

  <ul>

  <li>Basic Support for Equivalence Relations: a review of equivalence
  relations, refinement, and congruence</li>

  <li>Salient Facts about the ACL2 Rewriter: a review of how the rewriter
  works</li>

  <li>Using Congruence Rules to Generate Acceptable Equivalences for
  Subterms: an illustration of how congruence rules are used to determine the
  equivalences the rewriter is permitted to use</li>

  <li>Debugging Tools: How to see what equivalences are permitted while
  rewriting the current target and how to see how the set evolved as the
  rewriter descended from the top-level goal.</li>

  </ul>

  <h3>Basic Support for Equivalence Relations</h3>

  <p>If you do not know what the following ACL2 macro forms do, you should
  see their documentation.</p>

  <code>
  ; prove and store that eqv is an equivalence relation:

  (defequiv eqv)

  ; prove and store that the equivalence relation eqv1
  ; refines the equivalence relation eqv2

  (defrefinement eqv1 eqv2)

  ; prove and store that the equivalence relation eqv1 is a congruence relation
  ; for the kth argument of the function f, preserving the equivalence relation
  ; eqv2.

  (defcong eqv1 eqv2 (f x1 ... xn) k)
  </code>

  <p>An example of the last form is</p>

  <code>
  (defcong set-equal iff (member e x) 2)
  </code>

  <p>which essentially expands to</p>

  <code>
  (defthm set-equal-implies-iff-member-2
    (implies (set-equal x y)
             (iff (member e x)
                  (member e y)))
    :rule-classes (:congruence))
  </code>

  <p>(ACL2 actually generates a different variable name in place of @('y')
  above.)</p>

  <p>Helpful documentation topics include @(see equivalence), @(see
  refinement), @(see congruence), @(tsee defequiv), @(tsee defrefinement), and
  @(tsee defcong).</p>

  <h3>Salient Facts about the ACL2 Rewriter</h3>

  <ul>

  <li>Goals, which are represented as clauses, are simplified by rewriting each
  literal in turn, assuming the other literals false.</li>

  <li>When a term is rewritten (under some assumptions) the rewriter is given
  an @(see equivalence) relation to maintain, i.e., the output of the rewriter
  must be equivalent in that sense to the input, under the assumptions.</li>

  <li>The initial equivalence relation to be maintained while rewriting a
  literal is @(tsee iff).</li>

  <li>Each @(':')@(tsee rewrite) rule in ACL2 effectively concludes with a term
  of the form @('(eqv lhs rhs)'), where @('eqv') is an equivalence relation.
  Such a rule may be used to replace instances of @('lhs') by the corresponding
  instance of @('rhs'), and maintains the equivalence relation @('eqv').  But
  the rule is only applicable if @('eqv') <i>refines</i> the equivalence
  relation to be maintained by rewrite.  See @(see refinement).</li>

  <li>If the term to be rewritten is a function call, @('(fn a1 ... ak)'),
  the rewriter rewrites each @('ai') to, say, @('ai''), before applying rules
  to @('(fn a1' ... ak')').  To be more precise, when the ACL2 rewriter is
  asked to rewrite @('(fn a1 ... an)') maintaining some equivalence @('eqv'),
  it first rewrites each @('ai'), maintaining an equivalence generated from the
  congruence rules about how to rewrite the @('i')th argument of @('fn')
  maintaining @('eqv').  Suppose each @('ai') is thus rewritten to some other
  term @('ai'').  That is, @('(fn a1 ... an)') is transformed to @('(fn a1'
  ... an')') which is known to be @('eqv')-equivalent to @('(fn a1 ... an)').
  Then the rewriter applies all the @('eqv') rules it knows to @('(fn b1
  ... bn)').</li>

  <li>How the rewriter uses the known @(see congruence) rules to determine
  the equivalence relation to be maintained while rewriting each @('ai') is
  illustrated below.</li>

  <li>@('Equal') refines all equivalence relations.</li>

  <li>@('Equal') maintains all equivalence relations across all argument
  positions of all functions.</li>

  </ul>

  <h3>Using Congruence Rules to Generate Acceptable Equivalences for
  Subterms</h3>

  <p>In this section show how ACL2 generates the equivalence relation it will
  maintain when diving into subterms.  We do so by discussing a couple of
  contrived examples.  The actual script for these examples is in
  @('books/demos/geneqv.lisp').</p>

  <p>Our examples use the following functions.</p>

  <ul>

  <li>@('Len') is an ACL2 primitive that determines the number of elements
  in a list.</li>

  <li>@('(perm x y)') determines whether @('x') is a permutation of @('y'),
  i.e., whether each element that occurs in either @('x') or @('y') occurs in
  both the same number of times.  For example @('(perm '(A B A C) '(C B A A))')
  is true, but @('(perm '(A B A C) '(A B B C))') is false.</li>

  <li>@('(pairwise-iff x y)') determines whether corresponding elements of
  @('x') and @('y') are propositionally equivalent (i.e., @('IFF')-equivalent).
  For example, @('(pairwise-iff '(T NIL T) '(1 NIL A))') is true (since both
  @('1') and @('A') are non-@('NIL') and thus propositionally equivalent to
  @('T')), but @('(pairwise-iff '(T NIL T) '(1 NIL NIL))') is false.</li>

  <li>Both @('perm') and @('pairwise-iff') can be proved to be @(see
  equivalence) relations.</li>

  <li>Both @('perm') and @('pairwise-iff') are congruence relations for the
  first argument of @('len') that maintain @('equal')ity of @('len').

  <code>
  (defthm perm-implies-equal-len-1
    (implies (perm x y)
             (equal (len x)
                    (len y)))
    :rule-classes (:congruence))

  (defthm pairwise-iff-implies-equal-len-1
    (implies (pairwise-iff x y)
             (equal (len x)
                    (len y)))
    :rule-classes (:congruence))
  </code>
  </li>
  </ul>

  <p>Now consider proving</p>

  <code>
  (defthm example-thm-1
    (equal (len (isort (norml x)))
           (len x))
    :rule-classes nil)
  </code>

  <p>Before we start you should understand that there are many ways to prove
  this little theorem.  The most straightforward is just to prove that
  @('(len (isort x))') is @('(len x)') and to prove @('(len (norml x))') is
  @('(len x)').  In this case, where the functions involved are @('isort') and
  @('norml'), those theorems are easy to prove.  But for some functions in
  those roles of a problem like this it is easier to appeal to the properties
  of certain equivalence relations.  That's what we'll do here.</p>

  <p>If you run the @('defthm') above, the prover (after preprocessing)
  eventually calls the rewriter on the @('equal') term, requiring it to
  maintain @('iff').  The rewriter then dives into the two arguments, rewriting
  @('(len (isort (norml x)))') first, maintaining @('equal')ity.</p>

  <p>The rewriter then dives into the first argument of the @('len') term,
  @('(isort (norml x))').  The congruence rule @('perm-implies-equal-len-1')
  above tells it that @('equal')ity of the @('len') term is maintained if the
  first argument is rewritten maintaining the @('perm') equivalence.  In
  addition, the congruence rule @('pairwise-iff-implies-equal-len-1') tells it
  that @('equal')ity of the @('len') term is also maintained if the first
  argument is rewritten maintaining the @('pairwise-iff') equivalence.</p>

  <p>Thus, when rewriting @('(isort (norml x))') the rewriter can use any
  rewrite rule that maintains @('perm'), any rewrite rule that maintains
  @('pairwise-iff'), and, of course, any rewrite rule that maintains
  @('equal').  In addition, of course, it can use any rewrite rule that
  maintains a refinement of any of these equivalence relations.  This
  ``generated equivalence'' or ``geneqv'' is denoted by a set containing the
  named equivalence relations and the justifying congruence rules.</p>

  <p>The geneqv just derived is represented internally as</p>

  <code>
  ((5658 PAIRWISE-IFF
         :CONGRUENCE PAIRWISE-IFF-IMPLIES-EQUAL-LEN-1)
   (5651 PERM
         :CONGRUENCE PERM-IMPLIES-EQUAL-LEN-1))
  </code>

  <p>Ignoring the two numbers, we see two pairs, each naming an equivalence
  relation and the @(see rune) that justifies its use here.  The numbers are
  session-specific indices uniquely associated with the two runes that allow
  ACL2 to determine quickly if the runes are enabled.  Note that we do not
  include an entry for @('EQUAL') since it maintains every equivalence relation
  in every argument position of every function.  Indeed, if you see a geneqv of
  @('NIL') it means @('EQUAL') is the only acceptable equivalence relation in
  that context.</p>

  <p>Debugging tools in ACL2 typically display the geneqv above as</p>

  <code>
  ((PAIRWISE-IFF PAIRWISE-IFF-IMPLIES-EQUAL-LEN-1)
   (PERM PERM-IMPLIES-EQUAL-LEN-1))
  </code>

  <p>or even</p>

  <code>
  (PAIRWISE-IFF PERM).
  </code>

  <p>We discuss debugging tools that display geneqvs below.</p>

  <p>But what does this geneqv buy us during this proof?  Recall where we were
  in the proof discussed above.  We're rewriting @('(isort (norml x))')
  maintaining @('(PAIRWISE-IFF PERM)').  If the user had proved the following
  two rewrite rules</p>

  <code>
  (defthm perm-isort                ; isort preserves perm
    (perm (isort X) X))

  (defthm pairwise-iff-norml        ; norml preserves pairwise-iff
     (pairwise-iff (norml x) x))
  </code>

  <p>then the rewriter would replace @('(isort (norml x))') by @('(norml
  x)') using the first rule, since @('perm') is a refinement of the geneqv, and
  then the rewriter would rewrite that and replace it by @('x') using the
  second rule, since @('pairwise-iff') is also a refinement of the geneqv.
  Note that neither of these replacements preserve @('equal')ity, but they are
  permitted because they preserve the @('equal')ity of the @('len')s.</p>

  <p>Thus, @('(equal (len (isort (norml x))) (len x))') has been simplified to
  @('(equal (len x) (len x))') which further simplifies to @('t') and the proof
  is done.</p>

  <p>The Community Book @('"books/demos/geneqv-test-book.lisp"') (which
  executes the commands in books/demos/geneqv-test-input.lsp) contains this and
  other examples.</p>

  <h3>Debugging Tools</h3>

  <p>Generated equivalence relations are never mentioned or displayed in the
  prover output.  But of course they are crucial since they determine which
  rewrite rules can be used.  If a rule was expected to be used in a proof or
  proof attempt but was not used it might be because the rule's equivalence
  relation failed to be a refinement of the geneqv in effect when the intended
  target was encountered.  If @(tsee brr) is enabled and a @(tsee monitor)ed
  rule is tried by the rewriter but does not fire because it failed the
  refinement test, a @(see break-rewrite) interactive break occur.  See @(see
  refinement-failure) for some advice for how you might respond to such a
  failure.</p>

  <p>From within a break-rewrite break the @(tsee brr-commands) @(':path') will
  print the ``path'' from the current top-level goal down to the call of the
  rewriter on current @(':target') term.  Like a call stack, the path is
  composed of ``frames,'' most of which describe calls of the rewriter but some
  of which are calls of other system functions (like the @(tsee
  linear-arithmetic) procedure) that orchestrate other calls to the rewriter.
  As of Version  8.6, each frame of the @(':path') that describes the attempt
  to apply a particular rewrite rule will display the name of the equivalence
  relation used by the rule (unless that name is @('equal')).  Every frame
  describing a call of the rewriter includes the geneqv to be maintained as the
  target is rewritten (unless the geneqv is @('nil') which denotes the
  @('equal')ity relation).  The noted exceptions are intended to shorten the
  output in the most common cases: rewriting with @('equal') and maintaining
  equality.</p>

  <p>In addition, from within such a break the brr-command @(':geneqv') will
  print the geneqv for the current target.</p>")

(defxdoc generalize
  :parents (rule-classes)
  :short "Make a rule to restrict generalizations"
  :long "<p>See @(see rule-classes) for a general discussion of rule classes,
 including how they are used to build rules from formulas and a discussion of
 the various keywords in a rule class description.</p>

 @({
  Example:
  (defthm integer-listp-rev
    (implies (integer-listp x)
             (integer-listp (rev x)))
    :rule-classes :generalize)

  General Form:
  any theorem
 })

 <p>To use a @(':generalize') rule, the system waits until it has decided to
 generalize some term, @('term'), by replacing it with some new variable
 @('v').  If any @(':generalize') formula can be instantiated so that some
 non-variable subterm becomes @('term'), then that instance of the formula is
 added as a hypothesis.  Thus for the example above, if the term @('(rev x2)')
 is generalized to the variable @('rv') during a proof, then the following is
 added as a hypothesis when generalizing to a new goal.</p>

 @({
  (implies (integer-listp x2)
           (integer-listp rv))
 })

 <p>At the moment, the best description of how ACL2 @(':generalize') rules are
 used may be found in the discussion of ``Generalize Rules,'' page 248 of A
 Computational Logic Handbook, or ``Generalization,'' page 132 of
 ``Computer-Aided Reasoning: An Approach.''  Also see @(see
 introduction-to-the-theorem-prover) for detailed tutorial on using ACL2 to
 prove theorems, which includes some discussion of generalization.</p>")

(defxdoc generalized-booleans
  :parents (common-lisp)
  :short "Potential soundness issues related to ACL2 predicates"
  :long "<p>The discussion below outlines a potential source of unsoundness in
 ACL2.  Although to our knowledge there is no existing Lisp implementation in
 which this problem can arise, nevertheless we feel compelled to explain this
 situation.</p>

 <p>Consider for example the question: What is the value of @('(equal 3 3)')?
 According to the ACL2 axioms, it's @('t').  And as far as we know, based on
 considerable testing, the value is @('t') in every Common Lisp implementation.
 However, according the Common Lisp draft proposed ANSI standard, any
 non-@('nil') value could result.  Thus for example, @('(equal 3 3)') is
 allowed by the standard to be @('17').</p>

 <p>The Common Lisp standard specifies (or soon will) that a number of Common
 Lisp functions that one might expect to return Boolean values may, in fact,
 return arbitrary values.  Examples of such functions are @(tsee equal), @(tsee
 rationalp), and @(tsee <); a much more complete list is given below.  Indeed,
 we dare to say that every Common Lisp function that one may believe returns
 only Booleans is, nevertheless, not specified by the standard to have that
 property, with the exceptions of the functions @('not') and @('null').  The
 standard refers to such arbitrary values as ``generalized Booleans,'' but in
 fact this terminology makes no restriction on those values.  Rather, it merely
 specifies that they are to be viewed, in an informal sense, as being either
 @('nil') or not @('nil').</p>

 <p>This situation is problematic for ACL2, which axiomatizes these functions
 to return Booleans.  The problem is that because (for efficiency and
 simplicity) ACL2 makes very direct use of compiled Common Lisp functions to
 support the execution of its functions, there is in principle a potential for
 unsoundness due to these ``generalized Booleans.''  For example, ACL2's @(tsee
 equal) function is defined to be Common Lisp's @('equal').  Hence if in Common
 Lisp the form @('(equal 3 3)') were to evaluate to 17, then in ACL2 we could
 prove (using the @(':')@(tsee executable-counterpart) of @(tsee equal))
 @('(equal (equal 3 3) 17)').  However, ACL2 can also prove @('(equal (equal x
 x) t)'), and these two terms together are contradictory, since they imply
 (instantiating @('x') in the second term by @('3')) that @('(equal 3 3)') is
 both equal to @('17') and to @('t').</p>

 <p>To make matters worse, the standard allows @('(equal 3 3)') to evaluate to
 <i>different</i> non-@('nil') values every time.  That is: @('equal') need not
 even be a function!</p>

 <p>Fortunately, no existing Lisp implementation takes advantage of the
 flexibility to have (most of) its predicates return generalized Booleans, as
 far as we know.  We may implement appropriate safeguards in future releases of
 ACL2, in analogy to (indeed, probably extending) the existing safeguards by
 way of guards (see @(see guard)).  For now, we'll sleep a bit better knowing
 that we have been up-front about this potential problem.</p>

 <p>The following list of functions contains all those that are defined in
 Common Lisp to return generalized Booleans but are assumed by ACL2 to return
 Booleans.  In addition, the functions @(tsee acl2-numberp) and @(tsee
 complex-rationalp) are directly defined in terms of respective Common Lisp
 functions @('numberp') and @('complexp').</p>

 @({
  /=
  <
  =
  alpha-char-p
  atom
  char-equal
  char<
  char<=
  char>
  char>=
  characterp
  consp
  digit-char-p
  endp
  eq
  eql
  equal
  evenp
  integerp
  keywordp
  listp
  logbitp
  logtest
  lower-case-p
  minusp
  oddp
  plusp
  rationalp
  standard-char-p
  string-equal
  string<
  string<=
  string>
  string>=
  stringp
  subsetp
  symbolp
  upper-case-p
  zerop
 })")

(defxdoc generalizing-key-checkpoints
  :parents (introduction-to-the-theorem-prover)
  :short "Getting rid of unnecessary specificity"
  :long "<p>Suppose @('MEMBER') determines whether its first argument is a
 member of its second, and @('SUBSETP') determines whether every element of its
 first argument is a member of its second.  Suppose that you're trying to prove
 some Main Theorem and are told the formula below is a key checkpoint.  What
 should you do?</p>

 @({
  Key Checkpoint:
  (IMPLIES (AND (CONSP A)
                (INTEGERP (CAR A))
                (MEMBER (CAR A) B)
                (SUBSETP (CDR A) B)
                (NOT (SUBSETP (CDR A) (APPEND B C))))
           (MEMBER (CAR A) C))
 })

 <p>The key observation is that the fourth hypothesis implies the negation of
 the fifth.  Writing it in the contrapositive:</p>

 @({
  (IMPLIES (AND ...
                (SUBSETP (CDR A) B)
                ...)
           (SUBSETP (CDR A) (APPEND B C)))
 })

 <p>In fact, that is more complicated than it needs to be.  A ``correct''
 response to the key checkpoint above is to prove</p>

 @({
  (defthm subsetp-append
    (implies (subsetp a b)
             (subsetp a (append b c)))).
 })

 <p>A still better response is to prove this:</p>

 @({
  (defthm subsetp-append-2
    (implies (or (subsetp a b)
                 (subsetp a c))
             (subsetp a (append b c)))).
 })

 <p>This version is better because it handles both of the possibilities
 regarding whether @('a') is a subset of the arguments of the @('append').</p>

 <p>It would be nice if we could think of a ``strong'' version, one in which
 @('(SUBSETP a (APPEND b c))') is rewritten to some clearly simpler term, but
 nothing comes to mind.</p>

 <p>In any case, if you cannot see any obvious simplification of the individual
 terms in the Key Checkpoint, you should ask yourself whether there are
 connections between the various propositional parts (as here, with the fourth
 and fifth hypotheses).  It is a good heuristic to look for relations between
 parts with the same top-level function symbol (as here, with @('SUBSETP')).
 It is also a good heuristic to throw out parts of the formula that seem
 disconnected (as here, with the terms involving @('(CAR A)')).</p>

 <p>This discussion suggests several ``modes'' of looking at key checkpoints
 and the idea of trying the modes in sequence:</p>

 <p>(1) look for simplifiable combinations of function symbols within
 propositional components,</p>

 <p>(2) look for relations between propositional components, and</p>

 <p>(3) throw out irrelevant or weakly connected components.</p>

 <p>In all cases you are bringing to bear your intuitions about the
 <i>semantics</i> of the terms.  That is, you're not just slinging symbols.
 You should be looking out for obvious truths about individual parts of the
 checkpoints...  truths that are obvious to you but not to ACL2!</p>

 <p>Ultimately the three ``modes'' are the same and we do not really recommend
 adhering to the given sequence.  You're just looking for simpler theorems
 that, in combination, imply the checkpoint.  Keeping the ``modes'' in mind may
 help focus your attention so you consider all the plausible possibilities.
 After a little experience you'll find yourself looking for all these things
 simultaneously as part ``cleaning up'' the checkpoints.</p>

 <p>When your main goal theorems are harder than these, your main concern will
 be looking at a Key Checkpoint and asking yourself ``why is this true?''  But
 you don't want to do that until you've cleaned it up ``locally'' as much as
 possible and sometimes &mdash; more often than you might think &mdash; local
 considerations can prove many of your checkpoints.</p>

 <p>If you have been working your way through the tutorial introduction to the
 theorem prover, use your browser's <b>Back Button</b> now to return to @(see
 introduction-to-key-checkpoints).</p>")

(defxdoc gentle-introduction-to-acl2-programming
  :parents (start-here)
  :short "A Gentle Introduction to ACL2 Programming"
  :long "<h1>A Gentle Introduction to ACL2 Programming</h1>

 <h1><i>by</i></h1>
 <h1>J Strother Moore</h1>

 <h2>Abstract</h2>

 <p>ACL2 is a logic and programming language in which you can model computer
 systems, together with a tool to help you prove properties of those
 models. &ldquo;ACL2&rdquo; denotes &ldquo;A Computational Logic for
 Applicative Common Lisp&rdquo;.  The ACL2 programming language is a subset of
 <i>side-effect free</i> Common Lisp.  Mathematically speaking, all ACL2
 programs are functions.  When two calls of a function supply the same objects
 as inputs the calls return the same results.  If all you want to do is define
 ACL2 functions and run them, you don't need to know how to use ACL2 as a
 theorem prover.  This introduction is all you need.</p>

 <h2>Getting Started</h2>

 <p>If you haven't installed ACL2 on your machine, do so, by following the
 instructions at &ldquo;Obtaining, Installing, and License&rdquo; on the <a
 href='https://www.cs.utexas.edu/users/moore/acl2'>ACL2 Home Page</a>.  As
 those instructions make clear, to run ACL2 you'll need a Common Lisp
 implementation.  The instructions name several suitable ones.</p>

 <p>In addition to the @(see installation) instructions, the Home Page has a
 wealth of documentation.  You should visit &ldquo;The User's Manuals&rdquo;.
 There you'll see several versions of the manual, depending on whether you want
 information about utilities developed by users.  But we recommend that
 newcomers just look at the basic &ldquo;ACL2 User's Manual&rdquo;.  Explore it
 briefly just so you know how to find more information.  For example, type
 &ldquo;defun&rdquo; into the Jump to box and hit return.  You'll see details
 of how to define functions and there are many links in that discussion to
 related topics.  But don't try to understand @('defun') by reading all that.
 The manual is basically for users who are looking for technical information
 about features they basically know how to use.  Having learned how to explore
 the manual, put it aside for now and focus on this document!</p>

 <p>The interface to the ACL2 system is a read-eval-print loop.  It prints a
 prompt.  You type some command and hit return.  It reads and evaluates your
 command.  It prints the results.  And then it prompts you for your next
 input.</p>

 <p>You could use ACL2 with no other interface.  But most users prefer an
 environment in which they can prepare a command by editing the text before
 submitting it.  We use an Emacs shell buffer for that.  Other users use <see
 topic='@(url acl2-sedan)'>ACL2s</see>, which is an Eclipse plug-in.  This
 guide doesn't discuss the interface further and we just assume you can submit
 commands and see the output.  The examples we provide are from our Emacs
 interface.</p>

 <p>ACL2 is implemented (largely) in ACL2.  That is, almost all the system code
 is written in the ACL2 subset of Common Lisp.  The examples provided here were
 prepared under ACL2 Version 8.5.  Your output should be logically equivalent
 though the text may look a little different.</p>

 <p>Now fire up your ACL2.  You should see a prompt that looks like this</p>

 <code>
 ACL2 !&gt;
 </code>

 <p>Type &ldquo;:program&rdquo; and a return.</p>

 <code>
 ACL2 !&gt;:program
 ACL2 p!&gt;
 </code>

 <p>The @(':program') command tells ACL2 that subsequent definitions should merely be treated as
 ACL2 programs and not admitted into the logic.  (To admit a program into the logic requires proving
 that the program terminates.  We do not want to deal with proofs of any sort in this guide, so
 we'll stay in @(':program') mode.)</p>

 <p>Now type &ldquo;@('(+ 2 2)')&rdquo;.  You should see the answer, @('4')
 printed on the next line.  This illustrates the basic behavior of ACL2's
 read-eval-print loop.  The display below shows several other examples too.</p>

 <code>
 ACL2 !&gt;:program
 ACL2 p!&gt;(+ 2 2)
 4
 ACL2 p!&gt;(+ 1 2 3 4)
 10
 ACL2 p!&gt;(car '(hello world))
 HELLO
 ACL2 p!&gt;(cdr '(hello world))
 (WORLD)
 ACL2 p!&gt;(cons 'hello '(world))
 (HELLO WORLD)
 ACL2 p!&gt;
 </code>

 <p>Sometimes computations cause errors, most commonly due to type violations
 or resource limitations.  See the sections Type Errors and Stack Overflow
 below.</p>

 <p> Here is an ACL2 program that takes a linear list of numbers and constructs
 a linear list of their squares.  We've annotated it with Lisp comments.  ACL2
 ignores the comments.  We'll explain the syntax later.  For now we'll just
 interpret what this whole definition means.</p>

 <code>
 (defun square-all (x)

 ; Make a list of the squares of the elements of the list x.

   (cond
    ((endp x)                       ; If x is empty,
     nil)                           ; return the empty list.

    (t                              ; Otherwise,
     (cons (* (car x) (car x))      ; square the first element and
           (square-all (cdr x)))))) ; cons it onto the front of
                                    ; the squares of the rest.
 </code>

 <p>If you aren't sure what a &ldquo;linear list&rdquo; is just hang in and
 we'll get to it.  But you've probably figured out that @('nil') is the empty
 list, that @('cons') constructs a list by &ldquo;adding&rdquo; an element to
 the front of another list, that @('car') returns the first element of a
 non-empty list, and that @('cdr') returns all but the first element of a
 non-empty list.  Those deductions are right, as far as they go.</p>

 <p>Here is what it looks like if you submit the @('square-all') definition
 to the read-eval-print loop.  We have omitted most of the previous commands and their
 output, and we have omitted the comments we included in the display above.</p>

 <code>
 ACL2 !&gt;:program
 ...
 ACL2 p!&gt;(cons 'hello '(world))
 (HELLO WORLD)
 ACL2 p!&gt;(defun square-all (x)
   (cond ((endp x) nil)
         (t (cons (* (car x) (car x))
                  (square-all (cdr x))))))

 Summary
 Form:  ( DEFUN SQUARE-ALL ...)
 Rules: NIL
 Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
  SQUARE-ALL
 ACL2 p!&gt;
 </code>

 <p>
 Once @('square-all') is defined we can run it.  Here are some tests.</p>
 <code>
 ACL2 p!&gt;(square-all '(1 2 3 4 5))
 (1 4 9 16 25)
 ACL2 p!&gt;(square-all nil)
 NIL
 ACL2 p!&gt;(square-all '(-9 3/4 #c(0 5)))
 (81 9/16 -25)
 ACL2 p!&gt;
 </code>

 <h2>Data Types</h2>

 <p>
 ACL2 supports five very simple but rather abstract types of data: </p>
 <ul>
 <li>numbers,</li>
 <li>characters,</li>
 <li>strings,</li>
 <li>symbols (which includes the two Booleans @('T') and @('NIL')), and</li>
 <li>pairs or &ldquo;conses&rdquo;.</li>
 </ul>

 <p>Objects of each type are distinct.  That is, no number is a character or a
 string or a symbol or a pair.  Etc.</p>

 <p>
 All of these objects are &ldquo;first class&rdquo; in the sense that you can pass them
 in as values to functions, return them as values from functions, and store
 them in lists and trees.</p>

 <p>
 Many operators are provided for each type.  Each operator is a
 <i>function</i>.  </p>

 <p>
 <i>No ACL2 operator or function can modify, mutate, or otherwise alter the
 objects passed in as arguments.</i></p>

 <p>Since you're probably more familiar with conventional programming languages
 than functional (side-effect free) ones, let's talk operationally for a
 moment.  (This is a disservice to you!  The operational view is more
 complicated than the abstract mathematical view!)  ACL2 is implemented on top
 of a von Neumann architecture.  So what happens &ldquo;behind the
 scenes&rdquo; when the ACL2 function @('cons') is called on @('4') and @('5')?
 Mathematically it returns the pair &lt; @('4'), @('5') &gt; which is printed
 in ACL2 as @('(4 . 5)').  But operationally, some memory is allocated for a
 new object, then the representations of 4 and 5 are stored in two
 fields (called the <i>car</i> and <i>cdr</i> fields) of that object, that
 region of memory is effectively tagged to indicate that it represents a
 @('cons') pair, and a pointer to the newly allocated object is returned as the
 result of the call of @('cons').  When that result is printed by ACL2 it
 appears as @('(4 . 5)').  The italicized sentence above means <i>nothing you
 can do in ACL2 will change the contents of that newly allocated memory.</i> In
 most programming languages you could invoke some procedure or method to
 overwrite the contents of the <i>car</i> field of that object, changing it
 from @('4') to @('3').  No such procedure or method exists in ACL2.  The
 object returned by that call of @('cons') will print as the pair @('(4 . 5)')
 &mdash; will <i>be</i> the pair @('(4 . 5)') &mdash; for as long as you have
 access to the pointer returned by that call of @('cons').</p>

 <p>
 ACL2 expressions are just nests of function calls.  For example
 @('(factors (+ x (* 3 y)))') calls the function @('factors')
 on the value of <i>x+3y</i>.  (We define @('factors') below to
 return the list of prime factors of its input.)  The functions
 @('+') and @('*') are examples of functions that
 operate on numbers.</p>

 <p>
 Before we discuss ACL2 expressions further we must discuss the
 important issue of how you write down constants of each of the five types.</p>

 <p> A few examples suffice to illustrate the common ways to enter numeric
 constants: @('123'), @('22/7') and @('#c(3 5)').  Note that ACL2 provides
 &ldquo;infinitely precise&rdquo; rational numbers like @('1/3') and @('22/7').
 These are not floating point numbers; we don't provide floating point numbers.
 The rational @('2/3') could also be written @('4/6') &mdash; they are two
 different ways of writing the same number.  The ACL2 number @('#c(3 5)') is
 more conventionally written as the complex number <i>3+5i</i>.  ACL2 also
 supports writing numeric constants in binary, octal and hexadecimal notation,
 but we do not use that here.</p>

 <p>We will list some operations on numbers later.</p>

 <p> Here are examples of how to write character objects: @('#\A') and
 @('#\a') and @('#\Space').  Character objects are primarily used to build up
 strings.  While ACL2 provides functions for manipulating character objects (e.g., to
 recover their ASCII codes) we won't be using them here.</p>

 <p> Strings are delimited by the double quote mark, e.g., @('"This is an
 error message."') Again, there are functions more manipulating strings but we
 won't use them in this guide.</p>

 <p> This leaves us with symbols and conses.  Two symbols are easy to
 understand because they have counterparts in most programming languages:
 @('T') is a symbol but it is also ACL2's Boolean &ldquo;true&rdquo; object.
 @('NIL') is a symbol and is ACL2's Boolean &ldquo;false&rdquo; object.  When
 an ACL2 predicate is said to be false, we mean the predicate returns @('NIL').
 When an ACL2 predicate is said to be true, it usually means it returns @('T'),
 but more precisely it means it returns anything but @('NIL').  Oddly, Lisp and
 ACL2 also use the symbol @('NIL') as the &ldquo;empty list&rdquo;.</p>

 <p>
 Before we discuss other ACL2 functions however we must deal at length with
 symbols and conses.  Many first-time Lisp programmers do not really
 understand the idea of symbols as data or the idea of lists and trees as
 data.</p>

 <h2>Symbols</h2>

 <p> Symbols are sequences of alphabetic letters, signs and digits.  So @('X'),
 @('X*'), and @('ABC23') are symbols.  So are @('CAR'), @('IF'), and
 @('TRUE-LISTP').  Note that dashes and other signs do not &ldquo;break&rdquo;
 symbols into pieces.  @('TRUE-LISTP') is one symbol, not two symbols separated
 by a minus sign.</p>

 <p> Technically, a symbol can contain any sequence of characters and there are
 rules for writing symbols down so as to distinguish them from other constants.
 Using certain &ldquo;escape&rdquo; conventions you can actually write symbols
 containing spaces and parentheses, symbols composed entirely of digits, and
 symbols with other &ldquo;weird&rdquo; characters.  But we will not go into
 these conventions in this introduction.  We will limit ourselves to symbols
 that &ldquo;look like&rdquo; what you probably expect.  Most often, symbols
 start with an alphabetic character and then contain just alphabetic
 characters, signs and digits.  The first space, newline or parenthesis you
 encounter while reading a symbol marks the end of the symbol and isn't part of
 it.</p>

 <p> All programming languages (except binary machine code) have symbols at the
 syntactic level.  Symbols are used to denote variables, functions, operations,
 keywords, etc., in the syntax of most programming languages.  This is
 true in ACL2 too.  But ACL2 is a little different in that it also provides
 symbols as data objects.  That is, in addition to familiar data objects like
 numbers and strings, ACL2 provides symbols as a kind of data structure that
 can be manipulated.  For example, a symbol can be converted to a string
 object, or decomposed into its constituent characters, or several symbols can
 be concatenated to create a longer symbol.  But in this introduction we will
 just pass symbols around, compare them to other objects, and create
 lists (conses) containing symbols as elements.</p>

 <p> As noted, @('T') and @('NIL') are symbols with special significance.  They
 are our &ldquo;Booleans&rdquo; data objects and @('NIL') is used as the
 &ldquo;empty list&rdquo;.</p>

 <p> Symbols are more complicated than described above because in addition to
 their names they belong to &ldquo;packages.&rdquo; For example, there might be
 a symbol named @('ABS') in a package named @('"MATH"') and a symbol named
 @('ABS') in a package named @('"VECTORS"').  There is always one
 &ldquo;current package&rdquo; in ACL2 &mdash; you can select any package as
 the current package.  If @('"MATH"') were the current package, then when you
 write @('ABS') you denote the symbol @('ABS') in the @('"MATH"') package.
 If you mean the symbol @('ABS') in the @('"VECTORS"') package you would have
 to write @('VECTORS::ABS').  We will not use packages here.</p>

 <p> There is a special package called the @('"KEYWORD"') package.  The
 symbol @('ABS') in the @('"KEYWORD"') package can, of course, be written
 @('KEYWORD::ABS').  But special syntactic sugar also allows us to write
 @(':ABS') for that symbol.</p>

 <p> When we write symbols, case is unimportant (unless that previously
 mentioned &ldquo;escape&rdquo; convention is used).  When reading a symbol all
 characters are all uppercased.  That is, ACL2 reads the symbol @('x') as
 @('X').  The symbol @('The') is read as @('THE') and @('True-Listp') is read
 as @('TRUE-LISTP').  Thus, the choice of whether to write a symbol in
 uppercase, lowercase, or some mixture of cases is just a stylistic one.</p>

 <code>
 ACL2 p!&gt;'(Here is a list of SymBols!)
 (HERE IS A LIST OF SYMBOLS!)
 ACL2 p!&gt;'(This list contains a |Weird Symbol|)
 (THIS LIST CONTAINS A |Weird Symbol|)
 ACL2 p&gt;
 </code>

 <p>
 ACL2 provides ways to construct symbols from strings, ways to construct
 strings from lists of character objects, and ways to construct character
 objects from integers.  But elementary ACL2 programs rarely construct new
 symbols, strings and characters dynamically.  The symbols, strings and
 characters manipulated during most program executions are entered initially
 in the input data (e.g., by reading a command line or input file).
 Therefore, we do not bother to describe how to &ldquo;create&rdquo; symbols, strings
 and characters and none of our examples create these objects dynamically.</p>

 <h2>Lists</h2>

 <p>We first discuss how to write down &ldquo;cons pairs&rdquo; and &ldquo;
 list objects&rdquo;.  Later we will describe the operations on them.  There
 are many ways to write the same list constant.  This should not be surprising;
 the same thing is true of numeric constants.  Consider the fact that @('123'),
 @('000123'), @('+0123'), @('246/2') and @('#b1111011') are all ways to write
 down the same numeric constant.  The form you choose when writing a numeric
 constant is up to you and is often chosen to emphasize some aspect of the
 data.  For example, I might pad an integer with insignificant 0s to emphasize
 that it fits in a field of six digits, or I might unnecessarily write a + sign
 on the only positive integer in a data set.  Like numbers in other programming
 languages, lists are so common in ACL2 that there are many ways to write the
 same list constant but the choice of &ldquo;style&rdquo; is just that:
 stylistic.</p>

 <p> Most programming languages support the idea of some kind of record
 structure with fields containing other objects.  The only such record
 structure in ACL2 is the <i>ordered pair</i> or <i>cons pair</i>.  A cons pair
 is just a pair of two objects.  Sometimes we call a cons pair a &ldquo;list
 pair&rdquo; or a &ldquo;dotted pair&rdquo; or simply a &ldquo;list.&rdquo;</p>

 <p>
 Any two objects may be put together into a cons pair.  The cons pair
 containing the integer @('1') and the integer @('2') might be drawn as:</p>
 <code>
            *
           / \
          1   2
 </code>
 <p>
 or might be written in Cartesian coordinate notation as &lt;@('1'),@('2')&gt;.  But in ACL2
 it is written as the object @('(1 . 2)').  This is a single cons object in
 ACL2, with two integer objects as constituents.  The left-hand constituent
 is called the <i>car</i> of the pair.  The right-hand constituent is called the
 <i>cdr</i>.</p>

 <p>
 The tree we might draw as</p>
 <code>
            *
           / \
          1   *
             / \
            2   3
 </code>
 <p>
 or write in coordinate notation as &lt;@('1'), &lt;@('2'), @('3')&gt;&gt;, in
 ACL2 is written the object @('(1 . (2 . 3))').  The car of this object is the
 integer @('1').  The cdr of this object is the object @('(2
 . 3)').</p>

 <p>
 Similarly,</p>
 <code>
            *
           / \
          /   \
         *     *
        / \   / \
       1   2 3   4
 </code>

 <p> or &lt;&lt;@('1'), @('2')&gt;,&lt;@('3'), @('4')&gt;&gt; is written
 @('((1 . 2) . (3 . 4))').  Suppose <i>x</i> is the cons object just mentioned.
 Then the car of <i>x</i> is the object @('(1 . 2)') and the cdr is the object
 @('(3 . 4)').  Obviously, the car of the car of <i>x</i> is @('1').  The cdr
 of the car of <i>x</i> is @('2'), etc.</p>

 <p>
 The notation we are using to write list objects is called <i>dot
 notation</i>. It is a straightforward translation of the familiar
 coordinate notation in which parentheses replace the brackets and a dot
 replaces the comma.</p>

 <p>
 But there are other ways to write these conses.  This should not be
 surprising.  How many ways can you think of to write the number
 @('5')?  There are an infinite number!  @('5'),
 @('05'), @('005'), @('+000005'), etc., not to mention
 possibly @('#B101') and others.  Those are all just &ldquo;syntactic
 sugar&rdquo; for denoting one familiar object.  The sugars above might be
 described as &ldquo;you can add a leading @('0')&rdquo; and &ldquo;you can add a
 single leading plus sign on a positive number.&rdquo;</p>

 <p>
 Similarly, ACL2 has two rules that allow us to write cons pairs in
 a variety of ways.  The first rule provides a special way to write trees
 like:</p>
 <code>
           *
          / \
         1   nil
 </code>

 <p> namely, you can write @('(1 . nil)') or you can write @('(1)').  That is:
 if a cons pair has @('NIL') as its cdr, you can drop the &ldquo;dot&rdquo; and
 the @('NIL').</p>

 <p>
 The second rule provides a special way to write a cons pair that contains
 another cons pair in the cdr.  The rule allows us to write @('(')<i>x</i> @('. (...))')
 as @('(')<i>x</i> @('...)').  That is, when the cdr is a
 cons, you can drop the dot and the pair of balanced parentheses following it.</p>

 <p>
 Thus, the tree</p>
 <code>
           *
          / \
         1   *
            / \
           2   *
              / \
             3   nil
 </code>
 <p>
 can be written in any of the following ways.</p>
 <code>
 (1 . (2 . (3 . nil)))
 (1 . (2 . (3)))
 (1 . (2 3))
 (1 2 3)
 </code>
 <p>
 It can also be written in many other ways, e.g., @('(1 2 . (3 . nil))') and
 @('(1 . (2 3))').</p>

 <p>
 Binary trees that terminate in @('nil') on the right-most branch,
 such as the one above, are
 often called <i>linear lists</i>.  The <i>elements</i> of a list are the
 successive cars along the &ldquo;cdr chain.&rdquo;  That is, the elements are the car,
 the car of the cdr, the car of the cdr of the cdr, etc.  The elements of the
 list above are @('1'), @('2'), and @('3'), in that
 order.  If we let <i>x</i> denote that tree, i.e., let <i>x</i> be
 @('(1 2 3)'), then the car of <i>x</i> is @('1').  The cdr
 of <i>x</i> is the linear list @('(2 3)').  The car of the cdr of
 <i>x</i> is thus @('2').  The cdr of the cdr of <i>x</i> is the
 linear list @('(3)').  The car of the cdr of the cdr of <i>x</i>
 is @('3').  And the &ldquo;third cdr&rdquo; of <i>x</i> is @('nil').</p>

 <p>The linear list @('(A (B C D) E)') has three elements.  @('B') is not an
 element of that list, it is an element of an element.</p>

 <p>
 The following is a linear list of pairs.</p>

 <code>
      *
     / \
    *   \
   / \   \
  A   1   *
         / \
        *   \
       / \   \
      B   2   *
             / \
            *   \
           / \   \
          C   3   nil
 </code>
 <p>
 This list can be written @('((A . 1) (B . 2) (C . 3))').  In full
 dot notation it is written</p>
 <code>((A . 1) . ((B . 2) . ((C . 3) . NIL))).
 </code>

 <p>
 By the way, lists such as the one above are so common they
 have a name.  They are called <i>association lists</i> or
 <i>alists</i> and are used as keyed tables.  The list above associates
 the key @('A') with the value @('1'), the key @('B')
 with the value @('2'), etc.  Later we show functions for manipulating
 alists.</p>

 <p>
 Lists are often used to represent more elaborate data structures.  For
 example, an &ldquo;account&rdquo; might consist of a name, an id number, a
 balance and a list of transactions, laid out like this:</p>
 <code>
         *
        / \
       /   \
      /     \
     *       *
    / \     / \
   /   \   /   \
 name  id bal  trans
 </code>
 <p>
 An example of an account object might be</p>
 <code>
 (("John Smith" . 123456789)    ; Name and id
  .
  (1254 .                       ; balance in cents
    ((DEPOSIT (1 21 1999) 1000) ; transactions
     (WITHDRL (1 30 1999)  850)
     (WITHDRL (2  5 1999)  215))))
 </code>

 <p>Rather than refer to these four components in terms of the @('car') and
 @('cdr') of the account object most programmers would define functions with
 application-specific names like @('account-name'), @('account-id'), etc.
 Instead of building each account object with a nest of @('cons') expressions
 they would define @('(make-account name id bal trans)') to do the consing.</p>


 <h2>Expressions</h2>

 <p>We've seen that the basic idiom for defining a new function in ACL2 is to
 write</p>

 <code>
 (defun f (v1 ... vn) body)
 </code>

 <p>where @('f') is the name of the function, the @('vi') are its input
 parameters, and @('body') is an expression that computes the value of the
 function in terms of the parameters.  The <i>n</i> parameters must be distinct
 variable names and we say that <i>n</i> is the <i>arity</i> of the new
 function @('f').  But what are expressions?</p>

 <p>With a few exceptions, an expression is either</p>

 <ul>
 <li>a variable symbol,</li>

 <li>a constant expression,</li>

 <li>a call of a function of arity <i>n</i> on <i>n</i> argument
 expressions (sometimes called the <i>actuals</i>).</li>

 </ul>

 <p>Variable symbols are written in the same way that symbol objects are
 written, except @('T'), @('NIL'), and keywords may not be used as variable
 symbols.  Examples of variable symbols are thus @('X'), @('k'), @('temp3'),
 and @('init-val').</p>

 <p>There are two kinds of constant expressions: those that can just be written
 as ordinary objects and those that must be quoted.  Character objects,
 strings, numbers, @('T'), @('NIL'), and keywords are of the first kind.  They
 may be used as constant expressions without any additional signifying mark.
 All other symbols and all list objects must be preceded by a single quote
 mark (') to be used as constants in an expression.  Examples of constant
 expressions of the first kind are thus @('#\Space'), @('"EOF Error"'),
 @('128'), @('T'), @('NIL'), and @(':element').  Constant expressions of the
 second kind include @(''X'), @(''HELLO'), and @(''(MON WED FRI)').</p>

 <p>Function calls are written by writing an open parenthesis, the name of the
 function and the <i>n</i> argument expressions, all separated by whitespace,
 followed by a close parenthesis.  For example @('(cons (* (car x) (car
 x)) (square-all (cdr x)))') is a function call of the function @('cons') on
 two argument expressions.  The first argument is a call of @('*') on two
 expressions, both of which are calls of @('car') on the variable symbol
 @('x').  The second argument to the call of @('cons') is @('(square-all (cdr
 x))'), which is a call of @('square-all') on a call of @('cdr') on @('x').</p>

 <p>
 Consider the list object @('(CAR X)'), which we can draw as</p>
 <code>
      *
     / \
    CAR \
         *
        / \
       X  NIL.
 </code>

 <p>This object can be written as @('(CAR X)').  But that is also the way we
 write the expression that denotes a call of the function @('CAR') on @('X').
 So if we want to use that object in an expression we have to quote it to make
 it clear we mean the object rather than the expression.</p>

 <p>We have said that an expression is either a variable, a constant, or a
 function call of a function symbol of arity @('n') on @('n') argument
 expressions.  But there are exceptions to this simple characterization of
 expressions.  One exception is that some functions appear to take varying
 numbers of arguments.  For example, ACL2 allows @('+') and @('*') to take more
 than two arguments.  So @('(+ (* x x) (* 2 x y) (* y y))') is allowed.  We'll
 note other such functions when we use them here.  Another exception is a
 special notation for nested if-then-else expressions described below.  These
 exceptions are actually facilitated by a <i>macro</i> facility allowing the
 user to define new notation, but we will not discuss macros here even though
 we will use and explain some macros in our examples.  Finally, ACL2 permits
 calls of unnamed functions, called <i>lambda expressions</i>, but we won't use
 them explicitly in this introduction.  The reason we say
 &ldquo;explicitly&rdquo; is that we will use so-called @('let') expressions to
 introduce some local temporary variables and ACL2 understands
 @('let') expressions as applications of lambda expressions.  We'll explain
 when we introduce @('let').</p>

 <p>An example expression is</p>

 <code>
 (cons (cons 'square-all (cons x nil))
       (cons '=
             (cons (square-all x) nil)))
 </code>

 <p>provided @('square-all') has been defined as a function of arity 1.  Note
 that case is actually unimportant in symbols, whether they are function or
 variable names or data objects.  Unless special conventions are employed all
 symbols are read in uppercase.</p>

 <p>Expressions have <i>values</i> computed with respect to an environment
 assigning values to variable symbols.  For example, if @('square-all') is
 defined as previously shown and @('x') has the value @('(1 2 3)') then the
 value of the expression above is</p>

 <code>
 ((SQUARE-ALL (1 2 3)) = (1 4 9)).
 </code>

 <p>Here is the algorithm for determining the value of an expression in an
 environment. The value of a variable is just looked up in the environment.
 The value of a constant expression is the obvious object.  The value of a call
 of a defined function is computed by (a) evaluating the <i>n</i> argument
 expressions to obtain a sequence of <i>n</i> objects, (b) creating a new
 environment in which the function's <i>n</i> parameters are assigned those
 respective objects, and then (c) evaluating the body expression of the
 function in that new environment.  The value of a call of a primitive
 function, like @('*') or @('cons'), is determined by running special code on
 the values of the arguments.</p>

 <p>For example, suppose we have added this definition</p>

 <code>
 (defun sq (x) (* x x))
 </code>

 <p>and we are in an environment where @('x') has value @('5').  Then here is
 an annotated computation of the value of @('(sq (+ 1 x))').</p>

 <code>
 (sq (+ 1 x))
 =                ; evaluate argument of sq, when x = 5
 (sq 6)
 =                ; evaluate body of sq, when x = 6
 36.
 </code>

 <h2>Primitive Functions</h2>

 <p>The ACL2 system starts up with over eight thousand known functions, 32 of
 which are primitive (defined by special code rather than definitions).  The
 rest are defined.  Here is a brief summary of a few useful primitives.  We
 have biased this list to encourage merely integer arithmetic and list
 processing.  Some of the functions mentioned below are not actually primitive
 but are defined as simple compositions of primitives.  For example, @('(natp
 x)') is defined to be @('(and (integerp x) (<= 0 x))').  Other
 &ldquo;functions&rdquo; mentioned below are actually macros that expand into
 primitive expressions.</p>

 <ul>

 <li>@('(EQUAL x y)') &mdash; @('t') if @('x') and @('y') are the same
 object and @('nil') otherwise</li>

 <li>@('(IF x y z)') &mdash; @('y') if @('x') is non-@('NIL') and @('z') if
 @('x') is @('NIL').  Put more colloquially, @('(IF x y z)') means &ldquo;if
 @('x') is true, return @('y'), otherwise return @('z')&rdquo;</li>

 <li>@('(COND (p1 x1) (p2 x2) ... (T xn))') &mdash; an abbreviation for
 <code>
 (IF p1
     x1
     (IF p2
         x2
         (IF ...
             ...
             y)))
 </code></li>

 <li> @('(AND x1 ... xn)') &mdash; @('xn') if each @('xi') is non-@('nil'),
 and @('nil') otherwise </li>

 <li> @('(OR x1 ... xn)') &mdash; @('xi') for the first @('xi') that is
 non-@('nil'), @('nil') otherwise </li>

 <li> @('(NOT x)') &mdash; @('t') if @('x') is @('nil') and @('nil') otherwise </li>

 <li> @('(NATP x)') &mdash; @('t') if @('x') is a non-negative integer and @('nil') otherwise </li>

 <li> @('(INTEGERP x)') &mdash; @('t') if @('x') is an integer and @('nil') otherwise </li>

 <li> @('(RATIONALP x)') &mdash; @('t') if @('x') is a rational number and @('nil') otherwise </li>

 <li> @('(ZP x)') &mdash; @('nil') if @('x') is a positive integer and @('t') otherwise </li>

 <li> @('(+ x1 ... xn)') &mdash; sum of the @('xi') </li>

 <li> @('(* x1 ... xn)') &mdash; product of the @('xi') </li>

 <li> @('(- x y)') &mdash; @('x') minus @('y') </li>

 <li> @('(/ x y)') &mdash; quotient of @('x') divided by @('y') </li>

 <li> @('(< x y)') &mdash; @('t') if @('x') is less than @('y') and @('nil')
 otherwise </li>

 <li> @('(<= x y)') &mdash; @('t') if @('x') is less than or equal to @('y')
 and @('nil') otherwise </li>

 <li>@('(CONSP x)') &mdash; @('t') if @('x') is a cons pair and @('nil') otherwise </li>

 <li>@('(ATOM x)') &mdash; @('t') if @('x') is a not cons pair and @('nil') otherwise </li>

 <li>@('(ENDP x)') &mdash; @('t') if @('x') is @('nil') or a not cons pair and @('nil') otherwise </li>

 <li> @('(CONS x y)') &mdash; the ordered pair whose left-hand component is @('x') and whose right-hand component is @('y') </li>

 <li> @('(CAR x)') &mdash; left-hand component of @('x') if @('x') is a cons pair and @('nil') otherwise  </li>

 <li> @('(CDR x)') &mdash; right-hand component of @('x') if @('x') is a cons pair and @('nil') otherwise  </li>

 <li> @('(CADR x)') &mdash; @('(CAR (CDR X))') </li>

 <li> @('(CDDR x)') &mdash; @('(CDR (CDR X))') </li>

 <li> @('(LIST x1 x2 ... xn)') &mdash; @('(CONS x1 (CONS x2 ... (CONS xn NIL)))') </li>

 <li> @('(LIST* x1 x2 ... xn)') &mdash; @('(CONS x1 (CONS x2 ... xn))') </li>

 <li> @('(SYMBOLP x)') &mdash; @('t') if @('x') is a symbol and @('nil') otherwise </li>

 <li> @('(STRINGP x)') &mdash; @('t') if @('x') is a string and @('nil') otherwise </li>

 <li> @('(CHARACTERP x)') &mdash; @('t') if @('x') is a character and @('nil') otherwise </li>

 </ul>

 <p>You can learn more about these functions by executing them on some sample
 data.  For example, the value of @('(AND T 23 33)') is @('33'), @('(+ 1 2 3)')
 is @('6'), @('(ZP 0)') is @('T') but @('(ZP 3)') is false (i.e., @('NIL')).
 @('(LIST 1 (+ 2 2) (+ 3 3))') has the value @('(1 4 6)') but @('(LIST* 1 (+ 2
 2) (+ 3 3))') has the value @('(1 4 . 6)').</p>

 <p>Perhaps more interestingly, the value of @('(EQUAL (CONS (- 6 1) 7) (CONS
 5 (+ 5 2)))') is @('T').  &ldquo;Behind the scenes&rdquo; those two calls of
 @('CONS') return two different pointers to two different newly allocated
 regions of memory, but the <i>car</i> and <i>cdr</i> fields of both objects
 are the same, namely @('5') and @('7') respectively.  ACL2 cannot tell those
 two pointers apart.  Operationally, @('EQUAL') checks equality recursively
 down to the tips of both objects.  But logically, both @('CONS') expressions
 here return the pair @('(5 . 7)').</p>

 <h2>Common Patterns of Recursion</h2>

 <p>
 Most of your function definitions in ACL2 will fall into certain common
 schemes.  Here is an informal description of the three most common
 schemes.  We define the function @('visit') several different
 ways to illustrate common recursions.  (In ACL2 you are not allowed to
 define a function more than one way; there is no &ldquo;overriding,&rdquo; &ldquo;hiding,&rdquo;
 or &ldquo;overloading.&rdquo;  These multiple definitions are just a device for
 illustrating a lot of definitions without burdening you with many different
 names.)</p>

 <h3>Visiting every element of a linear list</h3>

 <code>
 (defun visit (lst ...)
   (cond ((endp lst) ...)              ; <i>No elements left to process.</i>
         (t .                          ; <i>Some elements to process:</i>
             .
              .
               (car lst)               ; <i>do something with this element</i>

               (visit (cdr lst) ...)   ; <i>and visit the rest.</i>
              .
             .
            .)))
 </code>
 <p>
 We illustrate this scheme in the next section.</p>

 <h3>Visiting every node and leaf in a binary tree</h3>

 <code>
 (defun visit (tree ...)
   (cond ((atom tree) ...)             ; <i>The tree is a leaf: do something.</i>

         (t .                          ; <i>The tree is an interior node:</i>
             . tree                    ; <i>do something with it,</i>
              .
                (visit (car tree) ...) ; <i> visit nodes in left branch, and</i>

              . (visit (cdr tree) ...) ; <i> visit nodes in right branch.</i>
             .
            .)))
 </code>

 <p>
 Visiting every element of a linear list is just the
 special case of exploring a binary tree in which we visit only the successive
 subtrees along the @('cdr') chain and consider the @('car')
 of each such subtree as the &ldquo;data,&rdquo; or element, to be processed.
 We illustrate this recursion below.</p>

 <h3>Visiting all the natural numbers from n to 0</h3>

 <code>
 (defun visit (n ...)
   (cond ((zp n) ...)                  ; <i>N &ldquo;is&rdquo; 0: finish up!</i>
         (t .                          ; <i>N is a positive integer:</i>
             . n                       ; <i>do something with it, and</i>
              .
               (visit (- n 1) ...)     ; <i>visit the naturals below it.</i>
              .
             .
            .)))
 </code>
 <p>
 The reason &ldquo;is&rdquo; is in quotation marks above is that @('(zp n)') is
 true if either @('n') is 0 or @('n') is not a natural number.
 For example, @('(zp -3)') and @('(zp 1/3)') both return true!
 So when @('(zp n)') is true you don't <i>really</i> know
 @('n') is 0 but you do know there is nothing more to do,
 if you're thinking of @('n') as a natural number.  When
 @('(zp n)') is false, you <i>know</i> @('n') is a positive
 integer.  The predicate @('zp') is just a convenient way to recur
 through natural numbers and guarantees to halt the recursion even if you call
 the function on &ldquo;unexpected&rdquo; input, whether numeric or not.</p>

 <h2>Computing Results</h2>

 <p>
 When you define a recursive function you often have the choice of computing
 the results &ldquo;on the way up&rdquo; or &ldquo;on the way down.&rdquo;</p>

 <p>
 Suppose @('x') is a linear list of numbers and you wish to sum them.
 Here are two ways:</p>
 <code>
 (defun sum-up (x)
   (cond ((endp x) 0)
         (t (+ (car x) (sum-up (cdr x))))))

 (defun sum-down (x temp)
   (cond ((endp x) temp)
         (t (sum-down (cdr x) (+ (car x) temp)))))
 </code>
 <p>
 For example @('(sum-up '(1 2 3 4))') is @('10') and
 @('(sum-down '(1 2 3 4) 7)') is @('17').
 Both definitions fit within the &ldquo;visiting every element of a
 linear list&rdquo; recurrence scheme.</p>

 <p>
 Note that @('sum-up') takes a list of numbers and returns their sum
 while @('sum-down') takes a list of numbers and some initial value
 and adds the numbers in the list to the initial value.  Of course,
 @('(sum-up x)') is equal to @('(sum-down x 0)') &mdash;
 but only because the operation of addition is insensitive to the order
 in which the additions are done.</p>

 <p>
 In many applications, the @('sum-up') style is clearer, as it is
 obvious how each element of the list is contributing to the final value.  In
 particular, each element is handled in exactly the same way regardless of
 what elements came before.  In the @('sum-down') style, the value of
 the temporary variable can, in principle, be used to affect the processing of
 subsequent elements.  Information about the previous elements is being passed
 down.  In more complicated functions written in the @('sum-down')
 style, one must carefully inspect how @('temp') is used to determine
 if it is just the final answer or is being used to direct the computation.</p>

 <p> Of course, sometimes information about the elements already visited is
 necessary to decide how to process subsequent ones, in which case the
 @('sum-down') style might be the appropriate choice.</p>

 <p> Finally, when these two functions are compiled in a straightforward way,
 the recursion in @(' sum-up') may a call stack while the recursion in @('
 sum-down') does not: @('sum-down') is <i>tail recursive</i>.  This means that
 the value of the recursive call is returned as the final answer and there is
 no need for the execution engine to &ldquo;remember&rdquo; to come back after
 the call to &ldquo;do something.&rdquo; In @('sum-up') the execution engine
 must &ldquo;remember&rdquo; to add the two intermediate results together.
 Tail recursive calls can be compiled as simple jumps or &ldquo;gotos&rdquo;
 and often result in faster executions and use of no additional stack space.
 But all such considerations depend critically on the sophistication of the
 compiler.</p>

 <h2>Saving Intermediate Results</h2>

 <p>
 ACL2 is applicative so it does not have assignment statements.  But it is
 possible to use &ldquo;local variables&rdquo; to save intermediate results.
 Here is a function that computes x^4 + y^4, i.e., the sum of the fourth
 powers of @('x') and @('y').</p>

 <code>
 (defun x4y4 (x y)
   (let ((x2 (* x x))            ; Let x2 be x^2 and, &ldquo;simultaneously,&rdquo;
         (y2 (* y y)))           ; let y2 be y^2.
     (+ (* x2 x2)                ; Compute x^4 by squaring x^2 and
        (* y2 y2))))             ; add it to y^4 computed similarly.
 </code>

 <p> For example, @('(x4y4 2 3)') is @('16') + @('81') or @('97').  The
 @('let') expression has two parts, a list of variable bindings followed by a body.
 The bindings are written as a list of elements.  Each element lists a variable
 name and a term.  The terms are evaluated in parallel and then all the
 variables are bound to the values of the corresponding terms.  Then the body
 is evaluated.  The value of the body is the value of the @('let').</p>

 <p>@('Let') expressions are formalized in ACL2 as applications of anonymous
 functions.  For example, @('(let ((v1 a1) (v2 a2)) (g v1 v2))') is actually
 transformed into @('((lambda (v1 v2) (g v1 v2)) a1 a2)') where the @('lambda')
 expression is an anonymous function with two parameters, @('v1') and @('v2'),
 and body @('(g v1 v2)').  The terms @('a1') and @('a2') that determine the
 values of the local variables in the @('let') become the argument expressions
 on which the anonymous function is called.</p>

 <p>
 While @('let') binds its variables in parallel, @('let*')
 binds its variables sequentially.  The expression</p>
 <code>
 (let* ((x2 (* x x))             ; Let x2 be x^2, and then
        (x4 (* x2 x2))           ; let x4 be x2^2, and then
        (x8 (* x4 x4)))          ; let x8 be x4^2.
       x8)                       ; Return x8.
 </code>
 <p>
 computes @('x')^8.</p>

 <p>
 Here is an example of a common use of @('let').  Suppose you wish
 to find the length of the longest branches in a binary tree.  The function
 @('depth') does that.  It is an example of the &ldquo;visit every node
 in a binary tree&rdquo; scheme.</p>
 <code>
 (defun depth (x)
   (cond ((atom x) 0)
         (t (let ((left-depth (depth (car x)))
                  (right-depth (depth (cdr x))))
               (if (&lt; left-depth right-depth)
                   (+ 1 right-depth)
                   (+ 1 left-depth))))))
 </code>

 <p>
 Just to illustrate the definition and list notation, consider the
 tree</p>
 <code>
           *
          / \
         /   \
        *     *
       / \   / \
      a   * e   *
         / \   / \
        b   * f   g
           / \
          c   d
 </code>
 <p>
 The longest branches in this tree have length four and terminate in either
 @('c') or @('d').  This tree can be written</p>
 <code>
 ((a . (b . (c . d))) . (e . (f . g)))
 </code>
 <p>
 or equivalently as @('((a b c . d) e f . g)').</p>

 <p>
 The expression @('(depth '((a b c . d) e f . g))') has value 4.</p>

 <p>
 We could have defined this function this way:</p>
 <code>
 (defun depth (x)
   (cond ((atom x) 0)
         (t (if (&lt; (depth (car x))
                   (depth (cdr x)))
                (+ 1 (depth (cdr x)))
                (+ 1 (depth (car x)))))))
 </code>
 <p>
 But this would execute less efficiently because after recurring into both the
 car and cdr of @('x') to determine which is deepest it recurs into
 one of them again to return the answer.  The use of @('let')
 eliminates this duplication of effort by saving the results of the earlier
 calls.</p>

 <p>
 Still a third way to define @('depth') might be</p>
 <code>
 (defun depth (x)
   (cond ((atom x) 0)
         (t (+ 1 (max (depth (car x))
                      (depth (cdr x)))))))
 </code>
 <p>
 where @('(max i j)') is defined to be @('(if (&lt; i j) j
 i)').  This definition executes almost as efficiently as the first
 one.  The values of the two recursive calls are passed to the subroutine
 @('max').  @('Max') uses @('i') twice and
 @('j') twice but now that &ldquo;duplication of effort&rdquo; only requires
 looking up the values of variables, just as in the @('let') case.</p>

 <h2>Sample Definitions</h2>

 <h1>Functions on Linear Lists</h1>

 <p>
 The next several functions all illustrate the &ldquo;visiting every element of
 a linear list&rdquo; recurrence scheme.</p>

 <code>
 (defun mem (e x)

 ; Return t or nil according to whether e is an element of x.

   (cond ((endp x) nil)
         ((equal e (car x)) t)
         (t (mem e (cdr x)))))
 </code>

 <p>
 Equivalently:</p>
 <code>
 (defun mem (e x)
   (if (endp x)
       nil
       (if (equal e (car x))
           t
           (mem e (cdr x)))))
 </code>
 <p>
 or even</p>
 <code>
 (defun mem (e x)
   (and (not (endp x))
        (or (equal e (car x))
            (mem e (cdr x)))))
 </code>
 <p>
 (Recall our caveat about multiple definitions of the same function.  If you
 want to try one of these definitions in ACL2, fine.  If you want to try all
 three, you'll have to give them distinct names.)</p>

 <p>
 For all three of the above definitions, the following examples hold:</p>
 <code>
 ACL2 p!&gt;(mem 'd '(a b c d e f g))
 T
 ACL2 p!&gt;(mem 'd '(a b c   e f g))
 NIL
 ACL2 p!&gt;
 </code>

 <p>
 Here is a function to concatenate two lists together:</p>
 <code>
 (defun app (x y)
   (if (endp x)       ;;; If x is exhausted,
       y              ;;;    then return y
       (cons (car x)  ;;;  else, cons the first element of x onto
             (app     ;;;     the list obtained by recursively appending
              (cdr x) ;;;     the rest of x
              y))))   ;;;     to y.
 </code>

 <p>Here are some examples of @('app').</p>

 <code>
 ACL2 p!&gt;(app '(1 2 3) '(a b c d))
 (1 2 3 A B C D)
 ACL2 p!&gt;(app '(1 2 3) nil)
 (1 2 3)
 ACL2 p!&gt;(app (app '(1 2 3) '(4 5 6)) '(7 8 9))
 (1 2 3 4 5 6 7 8 9)
 ACL2 p!&gt;
 </code>

 <p>
 Here is a function to find the first pair in an alist (if any) that binds a given
 key.</p>
 <code>
 (defun lookup (key alist)
   (cond ((endp alist) nil)             ;;; If alist empty, return nil,
         ((equal key (car (car alist))) ;;; elseif the first pair contains key,
          (car alist))                  ;;;    then return the first pair,
         (t (lookup key (cdr alist))))) ;;; else look in the rest of alist.
 </code>

 <p>Here are some examples.</p>

 <code>
 ACL2 p!&gt;(lookup 'b '((a . 1)(b . 2) (c . 3)))
 (B . 2)
 ACL2 p!&gt;(lookup 'd '((a . 1)(b . 2) (c . 3)))
 NIL
 ACL2 p!&gt;(lookup 'b '((a . 1)(b . 2) (b . 3)))
 (B . 2)
 ACL2 p!&gt;
 </code>

 <p>Note that only the first binding of the key matters.</p>

 <p>
 Here is a function to &ldquo;change&rdquo; the value of a key in an alist.  Note
 that it does not modify the alist but produces a new alist.</p>
 <code>
 (defun store (key val alist)
   (cond
     ((endp alist)                 ;;; If alist is empty,
      (list (cons key val)))       ;;;  then return an alist with one binding,
     ((equal key (caar alist))     ;;; elseif the first pair binds key,
      (cons (cons key val)         ;;;  then add the new binding to
            (cdr alist)))          ;;;  the rest of the alist,
     (t (cons (car alist)          ;;; else cons this pair onto the result
              (store               ;;;  of recursively putting a new binding
                key val            ;;;  of key to val in
                (cdr alist))))))   ;;;  the rest of alist.
 </code>

 <code>
 ACL2 p!&gt;(store 'b 7 '((a . 1) (b . 2) (c . 3)))
 ((A . 1) (B . 7) (C . 3))
 ACL2 p!&gt;(store 'x 26 '((a . 1) (b . 2)))
 ((A . 1) (B . 2) (X . 26))
 ACL2 p!&gt;(store 'c 3 '((a . 1) (b . 2) (x . 26)))
 ((A . 1) (B . 2) (X . 26) (C . 3))
 </code>

 <p>
 It is important to recall that ACL2 is functional (side-effect free)!
 Despite its name, @('store') does not change the alist it is given
 but returns a new one.  Consider</p>
 <code>
 ACL2 p!&gt;(let* ((alist1 '((a . 1) (b . 2) (c . 3)))
                (alist2 (store 'b 7 alist1)))
          (list (lookup 'b alist1)
                (lookup 'b alist2)))
 ((B . 2) (B . 7))
 ACL2 p!&gt;
 </code>

 <p> The above expression binds @('alist1') to an alist in which @('b') is
 associated with 2.  Then it uses @('store') to bind @('b') in @('alist1') to
 the new value @('7') and calls the result @('alist2').  Then it returns the
 list containing the values of looking up @('b') in each of the alists.
 You might think the answer would be @('((B . 7) (B . 7))') and it <i>would be
 if</i> @('store') actually changed @('alist1') to create @('alist2').  But in
 fact @('alist1') is not changed.  The answer is @('((B . 2) (B . 7))').</p>

 <h1>Functions on Binary Trees</h1>

 <p>
 Here is a function to count the number of tips of a binary tree.  This function
 illustrates the &ldquo;visiting every node of a binary tree&rdquo; scheme.</p>
 <code>
 (defun count-tips (x)
   (cond ((atom x) 1)                   ;;; X is a tip: it counts 1.
         (t (+ (count-tips (car x))     ;;; X is a node: sum the counts
               (count-tips (cdr x)))))) ;;; of the left and right subtrees.
 </code>
 <p>
 The function above does the computation &ldquo;on the way up.&rdquo;</p>

 <p>
 Here is a version that does it &ldquo;on the way down.&rdquo;</p>
 <code>
 (defun count-tips (x temp)
   (cond ((atom x) (+ 1 temp))          ;;; X is a tip: add its count to temp.
         (t                             ;;; Otherwise, x is a node:  Read the
                                        ;;; nest of two calls below inside-out:
                                        ;;; Count the tips in (car x) and add
                                        ;;; that into temp.  Use the result as
                                        ;;; temp when you count the tips in
                                        ;;; (cdr x).
          (count-tips (cdr x)
                      (count-tips (car x)
                                  temp)))))
 </code>
 <p>
 This function has one tail recursive call.</p>

 <p>
 Let @('x') be the tree</p>
 <code>
           *
          / \
         /   \
        *     *
       / \   / \
      a   * e   *
         / \   / \
        b   * f   g
           / \
          c   d
 </code>
 <p>
 which we can write as @(''((a b c . d) e f . g)').  Then
 @('(count-tips x)') is @('7') (here we mean to use
 the first version of the definition).  Similarly,
 @('(count-tips x 0)') is also @('7') (here we mean
 to use the second version).</p>

 <h2>Mutual Recursion</h2>

 <p>
 ACL2 requires that subroutines be defined before they are used in other
 definitions.  So what do you do if you have two functions, <i>f</i> and
 <i>g</i>, and <i>f</i> calls <i>g</i> and <i>g</i> calls <i>f</i>?
 You define them together.
 This is called <i>mutual recursion</i>.</p>

 <p>
 The example below shows a very inefficient way to factor a number into a list
 of primes.</p>
 <code>
 (mutual-recursion

 (defun factors (n)

 ; Collect the prime factors of n.

   (factors-below n (- n 1)))

 (defun factors-below (n m)

 ; Return the prime factors of n that are less than or equal to m.

   (cond ((or (zp m)
              (equal m 1))
          (list n))
         ((integerp (/ n m))
          (app (factors (/ n m))
               (factors m)))
         (t (factors-below n (- m 1)))))
 )
 </code>
 <p>
 We can read this as follows.  To determine the @('factors') of
 <i>n</i>, call @('factors-below') on <i>n</i> and <i>n-1</i> to
 collect all the factors of <i>n</i> less than or equal to <i>n-1</i>.  To
 find all the factors of <i>n</i> less than or equal to <i>m</i>, consider
 three cases.  First, if <i>m</i> is 0 or 1, return the list containing just
 <i>n</i>.  Second, if <i>n/m</i> is an integer (i.e., <i>m</i> divides
 <i>n</i>), then use @('app') to concatenate the factors of
 <i>n/m</i> to the factors of <i>m</i>.  Third (and otherwise), find the
 factors of <i>n</i> below <i>m-1</i>.</p>

 <p>We can run @('factors').  For example @('(factors 12)') returns @('(2 2
 3)').  If we call @('(factors 123456789)') the computation takes a while (27
 seconds on my laptop) and returns @('(3 3 3607 3803)').  @('(Factors (- (expt
 2 31) 1))') takes about 500 seconds and returns @('(2147483647)').</p>

 <h2>Returning and Using Multiple Values</h2>

 <p>It is sometimes useful to define functions that return more than one
 result.  Here is an example of a function that produces and uses multiple
 values.  The function explores a binary tree and counts (in its second
 argument, @('nodes')) how many cons nodes it sees and counts (in its third
 argument, @('tips')) how many tips it sees.  It returns both numbers as a list
 of length 2 (without actually creating the intermediate lists).</p>

 <code>
 (defun node-and-tip-count (x nodes tips)
   (cond
    ((atom x)                ;;; X is a tip.  Return a vector (list) of
     (mv nodes               ;;; two results: the number of nodes seen
         (+ 1 tips))         ;;; and the number of tips seen (plus 1 for x).
     )
    (t                       ;;; X is a cons node.

       (mv-let (nodes-in-car tips-in-car)
               (node-and-tip-count (car x) nodes tips)

               ;;; The two lines above locally bind the variables
               ;;; nodes-in-car and tips-in-car to the number of
               ;;; nodes and tips, respectively, computed by the
               ;;; recursive call of this function on (car x)
               ;;; and the current running counts of nodes and tips.

               ;;; Then, below, we count the number of nodes and
               ;;; tips in (cdr x), starting with the counts for
               ;;; the car (and adding one for the node x).

               (node-and-tip-count (cdr x)
                                   (+ 1 nodes-in-car)
                                   tips-in-car)))))
 </code>

 <p>
 For example,</p>
 <code>
 (node-and-tip-count '((a . b) . (c . d)) 0 0)
 = (3 4)
 </code>

 <p>Thus, the tree in question has 3 cons nodes and 4 (non-cons) tips.</p>

 <p>If you want to use multiple values you should read the ACL2 documentation
 on that topic.</p>

 <h2>Type Errors</h2>

 <p>The ACL2 programming language is untyped.  Objects have types that can be
 checked at runtime with predicates like @('integerp'), @('consp'), etc., but
 there is no syntactic typing.  Any function can be applied to any object and
 ACL2 comes up with some value.  It does this by defaulting ill-typed inputs to
 default values of the expected type.  For example, @('+') expects its
 arguments to be numbers.  If you supply a non-numeric input to @('+') it will
 use @('0') instead.  Thus, the value of @('(+ 3 T)') is @('3').  @('Car') and
 @('cdr') expect their arguments to be either a cons pair or @('nil').  (A
 special case in Lisp is that @('car') and @('cdr') return @('nil') on
 @('nil').)  If called on objects of the wrong type, @('car') and @('cdr')
 default the argument to @('nil').</p>

 <p>But when you start up ACL2, the read-eval-print loop is configured to
 check types as it evaluates.  Errors are signaled if types are violated.
 However, if you want it to just plow into ill-typed data and get whatever
 result the defaults produce, you can use the @(':set-guard-checking nil')
 command as shown in the session below.</p>

 <code>
 ACL2 p!&gt;(+ 2 2)
 4
 ACL2 p!&gt;(+ 2 T)


 ACL2 Error in TOP-LEVEL:  The guard for the function call (BINARY-+ X Y),
 which is (AND (ACL2-NUMBERP X) (ACL2-NUMBERP Y)), is violated by the
 arguments in the call (BINARY-+ 2 T).
 See :DOC set-guard-checking for information about suppressing this
 check with (set-guard-checking :none), as recommended for new users.
 To debug see :DOC print-gv, see :DOC trace, and see :DOC wet.

 ACL2 p!&gt;: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 p&gt;(+ 2 T)
 2
 ACL2 p&gt;(CAR 'ABC)
 NIL
 ACL2 p&gt;
 </code>

 <p>Note that the prompt changes after the @(':set-guard-checking') command
 above.  The exclamation mark (@('!')) in the standard prompt indicates that
 types are being checked.</p>

 <h2>Stack Overflow</h2>

 <p>Sometimes a computation will consume more space than your machine has.
 For example, the following function constructs a list of @('n') @('nil')s.</p>

 <code>
 (defun nils (n)
   (if (zp n)
       nil
       (cons nil (nils (- n 1)))))
 </code>

 <p>We can run it on small values of @('n').</p>

 <code>
 (nils 10) = (nil nil nil nil nil nil nil nil nil nil)
 </code>

 <p>So that we don't have to read long lists of @('nil')s below we just take
 the length of the result with the ACL2 function @('len').</p>

 <code>
 ACL2 p!&gt;(len (nils 10))
 10
 ACL2 p!&gt;(len (nils 100))
 100
 ACL2 p!&gt;(len (nils 1000))
 1000
 ACL2 p!&gt;(len (nils 10000))
 10000
 ACL2 p!&gt;(len (nils 100000))
 100000
 ACL2 p!&gt;(len (nils 1000000))
 1000000
 ACL2 p!&gt;(len (nils 10000000))
 ***********************************************
 ************ ABORTING from raw Lisp ***********
 ********** (see :DOC raw-lisp-error) **********
 Error:  Stack overflow on value stack.
 ...
 :q
 ACL2 p!&gt;
</code>

 <p>But that last test, where we attempt to produce a list of ten million
 @('nil')s, causes a stack overflow in the Common Lisp configuration I'm
 running.  (If your Lisp causes a Lisp error and enters an interactive break
 you'll need to exit the break to return to ACL2.  Exactly how you do that
 depends on what Common Lisp you're running.  For example, in GCL and CCL, you
 type @(':q') followed by return, but in Allegro CL you type @(':reset')
 followed by return, and in CMU CL you type @('q') followed by return.)</p>

 <p>If you are interested in doing ``large'' calculations with ACL2 you will have
 to learn about how to compile definitions and how to use declarations to optimize
 code.  Those topics are beyond the scope of this document.</p>

 <p>However, often you can just code up a more efficient algorithm.  For
 example, the following tail-recursive version of @('nils') won't overflow the stack.</p>

 <code>
 (defun nils (n ans)
   (if (zp n)
       ans
       (nils (- n 1) (cons nil ans))))
 </code>

 <p>So now</p>

 <code>
 ACL2 p!&gt;(len (nils 10000000 nil))
 10000000
 ACL2 p!&gt;(len (nils 100000000 nil))
 100000000
 ACL2 p!&gt;(len (nils 1000000000 nil))
 1000000000
 ACL2 p!&gt;
 </code>

 <p>Of course, it will eventually use up all the memory.</p>

 <p>The tests above sort of suggest we're interested in the question &ldquo;Does @('(nils n nil)') always return a
 list of length @('n')?&rdquo;  If that is the question, then (a) you'll never answer it by running all possible
 tests, and (b) you are using exactly the right tool!</p>

 <p>The ACL2 system includes a theorem prover.  Below we show the commands you
 need to execute to answer the question in the affirmative.  We've elided the
 output from these commands.</p>

 <code>
 ACL2 p!&gt;:logic
 ACL2 !&gt;(verify-termination nils)
 ...
 ACL2 !&gt;(defthm lemma-about-nils
         (implies (natp n)
                  (equal (len (nils n ans))
                         (+ n (len ans)))))
 ...
 ACL2 !&gt;(defthm main-theorem-about-nils
         (implies (natp n)
                  (equal (len (nils n nil)) n)))
 ...
 </code>

 <p>That is, switch back into logic mode, admit @('nils') to the logic by
 proving termination, prove the general theorem that @('(nils n ans)') returns
 a list whose length is @('n') plus the length of @('ans'), when @('n') is
 natural number, and then prove the main theorem.  Your job as an ACL2
 &ldquo;theorem prover driver&rdquo; is to think of the commands.  The prover
 does the work to complete each of those steps.</p>

 <p>So maybe you should learn to prove theorems about your functions?  If so,
 see &ldquo;Recursion and Induction&rdquo;.</p>

 <h2>Conclusion</h2>

 <p>You should be ready at this point to use ACL2 as a programming language to
 implement lots of simple list processing algorithms.  Remember to go to the
 ACL2 User's Manual on the <a
 href='https://www.cs.utexas.edu/users/moore/acl2'>ACL2 Home Page</a> to learn
 about other functions and features.  If you need advice, check out the ACL2
 Help list under the Mailing Lists link.  The users who have volunteered to
 help are very responsive.</p>

 <p>One final piece of advice: it is always best to code the simplest algorithm
 you can.  Do not needlessly complicate your code.  Optimize for performance
 only after confirming that the straightforward implementation is too
 inefficient for your application.</p>

 ")

(defxdoc get-command-sequence
  :parents (history)
  :short "Return list of @(see command)s that are between two @(see command) descriptors"
  :long "@({
  Examples:
  (get-command-sequence 4 12)
  :gcs 4 12 ; same as above
  (get-command-sequence 4 :x)
  :gcs 4 :x ; same as above
 })

 <p>See @(see pcs) for a utility that prints abbreviated information about the
 @(see command)s that are between two command descriptors.  The utility
 @('get-command-sequence') &mdash; or simply @('gcs'), so that you can just
 type @(':gcs') at the prompt &mdash; has the same syntax but instead of
 printing, it simply returns the corresponding list of commands.  More
 precisely, it returns an @(see error-triple) @('(mv erp val state)') such that
 if @('erp') is not @('nil'), then @('val') is the desired list of
 commands.</p>")

(defxdoc get-cpu-time
  :parents (programming-with-state acl2-built-ins read-run-time)
  :short "Read elapsed cpu time"
  :long "<p>@('(Get-cpu-time state)') returns the elapsed cpu time in seconds
 since the start of the current ACL2 session.  See @(see read-run-time) for
 further documentation.</p>

 @(def get-cpu-time)")

(defxdoc get-enforce-redundancy
  :parents (redundant-events)
  :short "Query the @(see world) on whether redundancy is being enforced"
  :long "<p>See @(see set-enforce-redundancy) for relevant background.  For a
 given world, @('wrld') &mdash; typically, @('(w state)') &mdash; the value of
 @('(get-enforce-redundancy wrld)') is @('nil'), @('t'), or @(':warn')
 according to the most recent call of @('set-enforce-redundancy'), @('nil') by
 default.</p>")

(defxdoc get-event-data
  :parents (system-utilities output-controls)
  :short "Obtain data stored after at the conclusion of an event"
  :long "<p>Warning: This is a low-level system utility that may change
 somewhat over time.  For more details, see the ACL2 source code.</p>

 <p>Evaluation of the form @('(get-event-data key state)') returns the value of
 @('key') in an association list, which we call an <i>event-data alist</i>.
 Such an alist is the value of @(see state) global variable
 @('last-event-data').  (See @(see programming-with-state) for a discussion of
 state global variables.)  An event-data alist contains certain information
 stored at the conclusion of the immediately preceding event, some of which
 corresponds to the event's @(see summary).  We anticipate continuing to
 support at least the following keys, each with value @('VAL') as follows.</p>

 <ul>

 <li>@('ABORT-CAUSES'): @('VAL') is a list of reasons why the proof aborted.
 In particular, if the value @('INTERRUPT') is in the list, then the proof was
 interrupted (typically with Control-C).</li>

 <li>@('EVENT'): the @(see event).</li>

 <li>@('FORM'): @('VAL') is the ``context'' for the event, printed in the
 summary, @(see warnings), and @(see errors).</li>

 <li>@('HINT-EVENTS'): @('VAL') is as in the corresponding field of the event
 summary.</li>

 <li>@('NAMEX'): @('VAL') is 0, a single name, or a list of names; see
 comments in ACL2 source function @('access-event-tuple-namex').</li>

 <li>@('PROVER-STEPS-COUNTED'): @('VAL') is as in the corresponding field of
 the event summary.  Note: This value can be obtained using @(tsee
 last-prover-steps).</li>

 <li>@('RULES'): @('VAL') is as in the corresponding field of the event
 summary.</li>

 <li>@('SPLITTER-RULES'): @('VAL') represents the corresponding field of the
 event summary, as the list @('(case-split immed-forced if-intro)').</li>

 <li>@('SYSTEM-ATTACHMENTS'): @('VAL') lists the pairs @('(f . g)') for which
 @('f') is a system function with attachment @('g') (@(see defattach)), which
 differs from the attachment to @('f') when ACL2 starts up.</li>

 <li>@('TIME'): @('VAL') represents the corresponding field of the event
 summary, as the list @('(prove print proof-tree other)').</li>

 <li>@('WARNINGS'): @('VAL') is as in the corresponding field of the event
 summary.</li>

 </ul>")

(defxdoc get-guard-checking
  :parents (redundant-events)
  :short "Get the status most recently installed by @(tsee set-guard-checking)"
  :long "<p>See @(see set-guard-checking) for relevant background.  The value
 returned by @('(get-guard-checking)') is @('t') by default, but is the value
 most recently installed for @(see guard)-checking, typically supplied as the
 argument of a call of @(tsee set-guard-checking).</p>")

(defxdoc get-internal-time
  :parents (programming acl2-built-ins)
  :short "Runtime vs. realtime in ACL2 timings"
  :long "<p>The ACL2 system provides utilities that deal with elapsed time.
 These are most visibly used in reporting the time summaries when completing
 evaluation of @(see events).  For utilities that return elapsed cpu or run
 time, see @(see read-run-time), @(see get-cpu-time), and @(see get-real-time).
 Other time-related utilities include @(see with-prover-time-limit), @(see
 time-tracker), @(see time-tracker-tau), see @(see pstack).</p>

 <p>By default, these utilities all use an underlying notion of run time
 provided by the host Common Lisp implementation: specifically, the Common Lisp
 functions @('get-internal-run-time') for cpu time (or a slight variant if the
 host Lisp is a version of GCL that precedes 2.7.0) and
 @('get-internal-real-time') for real (wall clock) time.  While the latter is
 specified to measure elapsed time, the former is left to the implementation,
 which might well only measure time spent in the Lisp process.  Consider the
 following example, which is a bit arcane but basically sleeps for 2
 seconds.</p>

 @({
    (defttag t) ; to allow sys-call
    (make-event
     (prog2$ (sys-call "sleep" '("2"))
             (value '(value-triple nil))))
 })

 <p>A typical time @(see summary) might be as follows, drastically
 under-reporting the actual elapsed (real, wall clock) time.</p>

 @({
    Time:  0.01 seconds (prove: 0.00, print: 0.00, other: 0.01)
 })

 <p>However, you can instruct ACL2 to switch to using elapsed time (real time),
 in summaries and elsewhere, by evaluating the following form.</p>

 @({
    (assign get-internal-time-as-realtime t)
 })

 <p>To return to using runtime:</p>

 @({
    (assign get-internal-time-as-realtime nil)
 })

 <p>While the above example is rather silly, the issue becomes significant in
 time summaries for proofs that call out to external tools (see @(see sys-call)
 and see @(see clause-processor)).</p>

 <p>Note that a function @('get-internal-time') is defined in raw Lisp but is
 not available inside the ACL2 loop.  However, the expression @('(read-run-time
 state)') provides an interface to this function that is available inside the
 ACL2 loop; see @(see read-run-time), and also see @(see get-cpu-time) and
 @(see get-real-time).</p>")

(defxdoc get-persistent-whs
  :parents (wormhole)
  :short "Make a wormhole's status visible outside the wormhole"
  :long "@({
  General Form:
  (get-persistent-whs name state)
  })

 <p>@('Name') should be the name of a wormhole (see @(see wormhole)).  This
 function returns an @(see error-triple) of the form @('(mv nil s state)'),
 where @('s') is the persistent-whs of the named wormhole (i.e., the status of
 of wormhole stored outside of the ACL2 state).  The status is obtained by
 reading the oracle in the ACL2 @(tsee state) with @(tsee
 read-acl2-oracle).</p>

 <p>Recall that the status of a wormhole is some ACL2 object largely determined
 by the author of the wormhole.  It is always treated as a pair whose @('car')
 is the &ldquo;entry code&rdquo; (@(':enter') or @(':skip')) or, more
 precisely, is either @(':skip') or not @(':skip'), the latter case being
 treated like @(':enter').  But the @('cdr') of the status can be whatever the
 author of the wormhole chooses to hold the data of the wormhole.  When a
 wormhole is entered its persistent status, aka its persistent-whs, is used to
 configure the state of the read-eval-print loop the user sees inside the
 wormhole.  In particular, upon entry the persistent-whs is moved to the value
 of the state global variable @(''wormhole-status') and is thus accessible via
 @('(f-get-global 'wormhole-status state)').  We call this copy of the status
 the ephemeral-whs because when the wormhole is exited the ephemeral-whs is
 moved to the @('persistent-whs') and the state global @(''wormhole-status')
 is restored to whatever value it had when the wormhole was entered.</p>

 <p>See @(tsee wormhole-status) for a discussion of these two senses of the
 status of a wormhole.  See also @(see wormhole-programming-tips).</p>")

(defxdoc get-real-time
  :parents (programming-with-state acl2-built-ins read-run-time)
  :short "Read elapsed real time"
  :long "<p>@('(Get-real-time state)') returns @('(mv rtime state)') where
  @('rtime') is the elapsed real (wall clock) time in seconds since the start
  of the current ACL2 session.  See @(see read-run-time) for further
  documentation.</p>

 @(def get-real-time)")

(defxdoc getenv$
  :parents (programming-with-state acl2-built-ins)
  :short "Read an environment variable"
  :long "<p>@('(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.  (Exception: if the value is not a legal ACL2
 string, say because it contains a character with @(tsee char-code) exceeding
 255, then an error is signaled.)  The logical story is that @('getenv$')
 reads its value from the @('oracle') field of the ACL2 @(tsee 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 (see @(tsee read-acl2-oracle)) and
 the returned state has the updated (popped) acl2-oracle.</p>

 @({
  Example:
  (getenv$ "PWD" state) ==> (mv nil "/u/joe/work" state)
 })

 <p>Also see @(see setenv$).</p>

 @(def getenv$)")

(defxdoc getprop
  :parents (world acl2-built-ins)
  :short "Access fast property lists"
  :long "@({
  General form:
  (getprop symb key default world-name world-alist)
 })

 <p>See @(see getpropc) for a convenient abbreviation, and see @(see world) for
 discussion of both utilities @('getprop') and @(tsee putprop).  Also 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.</p>

 @(def getprop)")

(defxdoc getpropc
  :parents (world acl2-built-ins)
  :short "Access fast property lists"
  :long "@({
  General form:
  (getpropc symb key &optional default world-alist)
 })

 <p>where @('default') is @('nil') if omitted, and @('world-alist') is @('(w
 state)') if omitted.  This is a convenient abbreviation for the common case in
 which @(tsee getprop) is used for system programming, with
 @(''current-acl2-world') as the (implicit, for @('getpropc'))
 world-name.</p>

 @(def getpropc)")

(defxdoc git-quick-start
  :parents (about-acl2)
  :short "Git quick start guide."
  :long "<p>The
 <a href='https://github.com/acl2/acl2'>ACL2 GitHub repository</a>
 contains the ``bleeding edge'' ACL2 source code and @(see community-books),
 available between ACL2 <see topic="ACL2____RELEASE-NOTES">releases</see>.</p>

 <p>Here we provide minimal instructions for working with the ACL2 GitHub
 repo.  Many git tutorials are available elsewhere on the web (e.g., <a
 href='https://docs.github.com/en/get-started'>at GitHub</a>).</p>

 <h2>For non-contributors (to use ACL2 without contributing changes):</h2>

 <p>Start by obtaining the ACL2 GitHub repository (this command makes a
 directory called @('acl2') that contains the current contents of the
 @('master') branch):</p>

 @({
 git clone https://github.com/acl2/acl2
 })

 <p>Later, to update your copy to get the latest changes:</p>

 @({
 cd acl2
 git pull
 })

 <p>Once you have ACL2, you will probably want to certify some books (see
 @(see books-certification)).</p>

 <h2>For infrequent contributors:</h2>

 For those only planning on contributing a few times per year (or less), see
 @(see github-commit-code-using-pull-requests).

 <h2>For frequent contributors:</h2>

 For those contributing on a monthly or weekly basis, see @(see
 github-commit-code-using-push).")

(defxdoc github-commit-code-using-push
  :parents (git-quick-start)
  :short "How to commit code to the books using direct push access."
  :long "<p>This guide is for contributors who commit to the repository
  often (e.g., monthly or weekly).  Such contributors will typically
  begin with the @(see github-commit-code-using-pull-requests) method, and
  after they are familiar with the process and community, will switch to
  this method.</p>

 <p> If you do not plan to commit your own changes, see @(see git-quick-start)
 instead.</p>

 <h2>(A) GETTING STARTED</h2>

 <p>Start by obtaining an up-to-date copy of the web-based GitHub
 repository (this command makes a directory called @('acl2') that contains the
 current contents of the @('master') branch).</p>

 @({
 git clone https://github.com/acl2/acl2
 cd acl2
 })

 <h2>(B) UPDATING</h2>

 <p>The following commands will update your directory to match the latest
 contents of the main ACL2 repository on GitHub.</p>

 @({
 git fetch --all
 git merge -m "Merge." remotes/origin/master
 })

 <h2>(C) CONTRIBUTING</h2>

 <p>To join the <a href='https://github.com/acl2/acl2/'>GitHub project</a>,
 please send email to one of the following individuals.</p>

 <ul>

 <li>Eric Smith (@('eric.smith@kestrel.edu'))</li>

 <li>David Rager (@('ragerdl@gmail.com'))</li>

 <li>Sol Swords (@('sswords@gmail.com'))</li>

 </ul>

 <p>After you have joined the project, you can proceed as follows when you are
 ready to contribute.</p>

 <h3>Make Changes and Test Them</h3>

 <ol>

 <li>Before beginning your edits, update, as in (B) above.</li>

 <li>Build an executable.

 @({
 make update LISP=<your_lisp>
 })</li>

 <li>Make book changes.  See the guidelines in the @(see how-to-contribute) topic
  (e.g., about updating the book release notes).</li>

 <li>Run a regression.

 @({
 (make -j 8 regression) >& make-regression.log
 })

 Note that the @('-j 8') option specifies the use of 8 hardware threads; feel
 free to omit it or use a more suitable number (especially if your computer has
 other than 8 hardware threads).</li>

 <li>Look for failures, as indicated by @('**') in the log.

 @({
 fgrep -a '**' make-regression.log
 })</li>

 <li>If there were failures, then go back to Step 3 above to make appropriate
 changes and re-test.</li>

 <li>Commit your changes.  First do @('git status') to see the list of all
 new/changed files:

 @({
 git status
 })

 Ensure that none of the reported additions/changes was unintentional.  Next,
 do @('git add') to add each file you want to commit (normally, everything
 reported by @('git status'), to match what was tested in the regression above):

 @({
 git add <file1> <file2> ...
 })

 Now commit your changes locally:

 @({
 git commit -m '<some message, with descriptive first line>'
 })

 The @('-m ...')  option is a log message, where the first line is a summary
 of your changes and additional lines give more details.  You can replace
 the @('-m ...') option by @('-F <filename>'), where @('<filename>') is the
 name of a file that contains your log message.</li>

 <li>Merge in remote changes, if any, by updating again as in (B) above.

 If the merge changed anything, go back to Step 4 above to ensure that your
 changes are compatible with the remote changes you just obtained.  If the
 merge did not change anything, continue to the next step (Contribute Your
 Changes).

 In rare cases, you may get a merge conflict (concurrent changes to the same
 files), in which case you will need to resolve the conflict by editing files
 and committing them (see the @('git commit') command above in Step 7).  Then
 go back to Step 4 above to test that everything is working.

 </li>

 </ol>

 <h3>Contribute Your Changes</h3>

 <p>The following command will update the main ACL2 repository on GitHub.</p>

 @({
  git push origin testing
 })

 <p>This will cause your changes to be merged into the @('testing') branch.
 From there, they will be automatically merged into @('master') if the automated
 regression testing system successfully tests them.</p>

 <p>Note: If you are changing someone else's files, or would like someone to
 review your changes, you might consider making a pull request instead of
 pushing directly.</p>")

(defxdoc github-commit-code-using-pull-requests
  :parents (git-quick-start)
  :short "How to commit code to the books using pull requests."
  :long "<p>This guide is for contributors who will commit to the repository
  rarely (e.g., a few times a year). If you find yourself committing more often,
  see @(see github-commit-code-using-push).</p>

 <p> If you do not plan to commit your own changes, see @(see git-quick-start)
 instead.</p>

 <p>A nice result of using pull requests is that all changes will be peer-reviewed
 before being committed.  Also, we sometimes call this method the <i>Fork and
 Pull</i> method.</p>

 <h2>(A) GETTING STARTED</h2>

 <ol>

 <li>Go to <a
  href="https://github.com/acl2/acl2">https://github.com/acl2/acl2</a> and
  click on the @('fork') button on the top-right.  Fork the repository into
  your GitHub space.  This will create a new repository at
  @('https://github.com/<your-github-username>/acl2').</li>

 <li>In your working space on your computer, create a @('clone') of your GitHub
  repository and @('cd') into it:

 @({
 git clone https://github.com/<your-github-username>/acl2
 cd acl2
 })</li>

 <li>Add the main ACL2 repository as a git remote:

 @({
 git remote add upstream https://github.com/acl2/acl2
 })</li>

 </ol>

 <h2>(B) UPDATING</h2>

 <p>The following commands will update your directory to match the latest
 contents of the main ACL2 repository on GitHub.</p>

 @({
 git fetch --all
 git merge -m "Merge." remotes/upstream/master
 })

 <h2>(C) CONTRIBUTING</h2>

 <h3>Make Changes and Test Them</h3>

 <ol>

 <li>Before beginning your edits, update, as in (B) above.</li>

 <li>Build an executable.

 @({
 make update LISP=<your_lisp>
 })</li>

 <li>Make book changes.  See the guidelines in the @(see how-to-contribute) topic
  (e.g., about updating the book release notes).</li>

 <li>Run a regression.

 @({
 (make -j 8 regression) >& make-regression.log
 })

 Note that the @('-j 8') option specifies the use of 8 hardware threads; feel
 free to omit it or use a more suitable number (especially if your computer has
 other than 8 hardware threads).</li>

 <li>Look for failures, as indicated by @('**') in the log.

 @({
 fgrep -a '**' make-regression.log
 })</li>

 <li>If there were failures, then go back to Step 3 above to make appropriate
 changes and re-test.</li>

 <li>Commit your changes.  First do @('git status') to see the list of all
 new/changed files:

 @({
 git status
 })

 Ensure that none of the reported additions/changes was unintentional.  Next,
 do @('git add') to add each file you want to commit (normally, everything
 reported by @('git status'), to match what was tested in the regression above):

 @({
 git add <file1> <file2> ...
 })

 Now commit your changes locally:

 @({
 git commit -m '<some message, with descriptive first line>'
 })

 The @('-m ...')  option is a log message, where the first line is a summary
 of your changes and additional lines give more details.  You can replace
 the @('-m ...') option by @('-F <filename>'), where @('<filename>') is the
 name of a file that contains your log message.</li>

 <li>Merge in remote changes, if any, by updating again as in (B) above.

 If the merge changed anything, go back to Step 4 above to ensure that your
 changes are compatible with the remote changes you just obtained.  If the
 merge did not change anything, continue to the next step (Contribute Your
 Changes).

 In rare cases, you may get a merge conflict (concurrent changes to the same
 files), in which case you will need to resolve the conflict by editing files
 and committing them (see the @('git commit') command above in Step 7).  Then
 go back to Step 4 above to test that everything is working.

 </li>

 </ol>

 <h3>Contribute Your Changes</h3>

 <p>The following command will update your fork on GitHub.</p>

 @({
  git push
 })

 You now need to create a <i>pull request</i>, where you request that changes
 from your fork be accepted into the main ACL2 repository.
 To achieve this:

 <ol>

 <li>Go to @('https://github.com/<your-github-username>/acl2').</li>

 <li>Click the @('New pull request') button (you can search for it with your
 browser).</li>

 <li>In the drop-down box labeled "base" (next to the box labeled "base
 fork"), change the value from "master" to "testing".</li>

 <li>Click @('Create pull request').</li>

 <li>Put a description of your changes in the comments section.
 You may want to quote text from your commit log messages.</li>

 <li>Click @('Create pull request').</li>

 </ol>
 At this point, the main ACL2 repository maintainers will be notified,
 check that things seem to be in order, and then either request modifications
 or adopt your changes.")

(defxdoc goal-spec
  :parents (hints output-controls)
  :short "To indicate where a hint is to be used"
  :long "@({
  Examples:
  "Goal"
  "goal"
  "Subgoal *1/3''"
  "subgoal *1/3''"
  "[2]Subgoal *1/3''"
 })

 <p>When @(see hints) are given to the theorem prover, a goal-spec is provided
 to specify the goal to which the @(see hints) are to be applied.  The @(see
 hints) provided are carried along innocuously until the named goal arises.
 When it arises, the @(see hints) are ``activated'' for that goal and its
 descendants.</p>

 <p>A legal goal specification may be extracted from the theorem prover's
 output.  Certain lines clearly label formulas, as in</p>

 @({
  Subgoal *1/3.2'
  (IMPLIES ... ...)
 })

 <p>and these lines all give rise to goal specifications.  In general, these
 lines all start either with ``Goal'' or ``Subgoal'' or else with those words
 preceded by a number in square brackets, as in</p>

 @({
  [1]Subgoal *1/3.2'
  (IMPLIES ... ...).
 })

 <p>A goal specification may be obtained by deleting any surrounding whitespace
 from such a line and embedding the text in string quotation marks.  Thus</p>

 @({
  "[1]Subgoal *1/3.2'"
 })

 <p>is the goal specifier for the goal above.</p>

 <p>As noted, a hint is applied to a goal when the hint's goal specification
 matches the name ACL2 assigns to the goal.  The matching algorithm is
 case-insensitive.  Thus, alternative goal specifications for the goal above
 are @('"[1]subgoal *1/3.2'"') and @('"[1]SUBGOAL *1/3.2'"').  The matching
 algorithm does not tolerate non-case discrepancies.  Thus,
 @('"[1]Subgoal*1/3.2'"') and @('" [1]Subgoal *1/3.2'"') are
 unacceptable.</p>

 <p>Sometimes a formula is given two names, e.g.,</p>

 @({
  Subgoal *1/14.2'
  (IMPLIES ...
           ...)
  Name the formula above *1.1.
 })

 <p>It is the first name (the one that starts with ``Goal'' or ``Subgoal'') and
 not the second which constitutes a legal goal-spec.  Roughly speaking, when
 the system prints the line containing the goal specification, it activates any
 @(see hints) that are attached to that goal-spec.  Consider the example above.
 Suppose @('Subgoal *1/14.2'') could be proved by using a certain lemma
 instance.  Then the appropriate entry in the @(see hints) would be:</p>

 @({
  ("Subgoal *1/14.2'" :use ...)
 })

 <p>This might surprise you because the system appears to do nothing to
 @('*1/14.2'') besides push it for a subsequent induction.  But actually
 between the time the system printed the goal-spec line and the time it decides
 to push the goal, you can think of the system as trying everything it has.  So
 a @('use') hint activated when @('Subgoal *1/14.2'') arises is just what you
 want.</p>

 <p>But what if you want to give an @(':induct') hint?  By the time induction
 is tried, the formula has been given the name @('*1.1').  Well, this is one
 you just have to remember:</p>

 @({
  ("Subgoal *1/14.2'" :induct ...).
 })

 <p>When the above hint is activated the @(':induct') directive short-circuits
 the rest of the processing and sends immediately the formula into the pool of
 goals to prove by induction.  The induct hint is attached to the formula in
 the pool and when the time comes to turn our attention to that goal, the
 induct advice is followed.</p>

 <p>You can probably figure out the naming conventions for goals after seeing
 some examples in prover output.  Let's discuss the use of the character @(''')
 for a suffix.  If a goal has a single subgoal then a prime is added; e.g., if
 @('"Subgoal 3.2"') has a single subgoal then it is named @('"Subgoal
 3.2'"') rather than @('"Subgoal 3.2.1"').  If in turn that goal has a
 single subgoal, it is named @('"Subgoal 3.2''"'); and so on.  When four or
 more primes would be generated, say, @('n') primes, then the suffix is
 @('"'n'"'); e.g., continuing the preceding example we get @('"Subgoal
 3.2'''"'), @('"Subgoal 3.2'4'"'), @('"Subgoal 3.2'5'"'), and so on.  If
 any of these generates at least two subgoals then any ``prime'' suffix is
 dropped; for example, if @('"Subgoal 3.2'5'"') has two subgoals then they
 are named @('"Subgoal 3.2.2"') and @('"Subgoal 3.2.1"').</p>

 <p>We conclude by emphasizing a point made above, that a hint is applied to a
 goal when the hint's goal specification matches the name ACL2 assigns to the
 goal.  If there is no such match, then the hint is ignored.  Consider the
 following example.</p>

 @({
  (thm (equal (append (append x y) z) (append x y z))
       :hints (("Subgoal *1/" :in-theory nil)))
 })

 <p>Normally, @(':in-theory') hints are inherited by subgoals (see @(see
 hints-and-the-waterfall)), so you might expect that the empty theory is used
 in @('Subgoal *1/2') and @('Subgoal *1/1').  But in fact, since there is no
 subgoal printed that is labeled @('Subgoal *1/'), the above @(':in-theory')
 hint is ignored.  The above example is in contrast to the following, where the
 hint makes the proof fail, because there really is a @('Subgoal *1/') in the
 proof this time.</p>

 @({
  (thm (implies (and (not (endp x)) (not (endp (cdr x))))
                (equal (append (append x y) z) (append x y z)))
       :hints (("Subgoal *1/" :in-theory nil)))
 })")

(defxdoc good-bye
  :parents (basics acl2-built-ins)
  :short "Quit entirely out of Lisp"
  :long "@({
  Examples:
  ACL2 !>(good-bye)
  ; [ACL2 is exited]

  ACL2 !>(good-bye 3)
  ; [ACL2 is exited with Unix exit status 3]
 })

 <p>Note: Your entire session will disappear forever when you evaluate
 @('(good-bye)').</p>

 <p>The command @('(good-bye)') quits not only out of the ACL2 @(see command)
 loop, but in fact quits entirely out of the underlying Lisp.  Thus, there is
 no going back!  You will <b>not</b> be able to re-enter the @(see command)
 loop after typing @('(good-bye)')!  All your work will be lost!!!</p>

 <p>This command may not work in some underlying Common Lisp implementations.
 In such cases, there is no harm in trying; ACL2 will let you know how to
 proceed if it cannot exit.</p>

 <p>In some systems, typing @('control-d') at the top-level ACL2 prompt
 (@('control-c control-d') if inside emacs) will call this function.</p>

 <p>The optional argument for @('good-bye') (default 0) indicates the
 Unix (Linux) exit status.  If it is not an integer, it will be treated as
 0.</p>

 <p>If you merely want to exit the ACL2 @(see command) loop, use @(':q')
 instead. (That can be risky; see @(see q)).</p>

 <p>We conclude with the following technical remark, to be ignored unless you
 are trying to do things in raw Lisp that involve quitting the session.  The
 mechanism that ACL2 and Lisp use for quitting the session is slightly
 involved.  In particular, if you trace the underlying raw Lisp function
 @('exit-lisp'), you may see that it is called twice; the second call happens
 while cleaning up from an @('unwind-protect') call.</p>")

(defxdoc granularity
  :parents (parallel-programming)
  :short "Limit the amount of parallelism"
  :long "<p>This @(see documentation) topic relates to the experimental
 extension of ACL2 supporting parallel execution and proof; see @(see
 parallelism).</p>

 <p>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.</p>

 <p>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.</p>

 @({
  (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)))))))
 })

 <p>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.</p>

 @({
  (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)))))))
 })

 <p>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').</p>

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

 <p>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:</p>

 @({
  (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)))))
 })

 <p>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
 @('SET::pmergesort-exec').</p>")

(defxdoc gratuitous-lambda-object-restrictions
  :parents (apply$)
  :short "Enforcement of logically unnecessary restrictions on @(':FN') slots"
  :long "<p>When a form is submitted to the ACL2's read-eval-print loop the
  terms in it are translated (``macroexpanded'') into ACL2's internal form, in
  which abbreviations like @('(cadr x)') are expanded away and constants are
  always quoted.  See @(see term) for details of the internal form.</p>

  <p>But translation also enforces a logically unnecessary restriction in
  argument positions of @(see ilk) @(':FN').  If a quoted @('consp') object
  whose @('car') is the symbol @('LAMBDA') occurs in a @(':FN') slot, translate
  insists that the object satisfy @(tsee well-formed-lambda-objectp).
  Well-formedness implies tameness, so any @('LAMBDA') object that passes this
  translate-time test will have the ``expected behavior'' under @('apply$').
  If a quoted ill-formed ``LAMBDA-like'' object is passed into a @(':FN')
  slot, an error is signaled.</p>

  <p>This is logically unnecessary because, like all ACL2 functions,
  @('apply$') can be called on any objects.  Indeed, ill-formed
  @('LAMBDA')-like objects induce some kind of default behavior by @('apply$')
  and can, sometimes, deliver non-erroneous values.</p>

  <p>But ground @('apply$') terms can be evaluated more quickly on well-formed
  @('LAMBDA') objects than on ill-formed ones.  See for example the discussion
  of performance in @(tsee print-cl-cache).  So this restriction is really
  motivated by a desire to encourage the exclusive use of well-formed
  @('LAMBDA') objects.</p>

  <p>Why would you want to call @('apply$') on ill-formed input?  The answer is
  that you might be trying to explore the semantics of @('apply$') by example.
  Since this is a time-honored methodology, we have made it possible to
  circumvent the translate-time check if you insist on feeding an ill-formed
  object into a @(':FN') slot.  Soundness is not imperiled but execution may
  slow down.</p>

  <p><i>Warning</i>: Using an ill-formed @('LAMBDA') object in a @(':FN') slot
  in a @('defun') will make it impossible to warrant the newly defined function
  because it will not pass the stringent tests necessary to analyze its ilks.
  See @(tsee defwarrant).  Basically these bypasses are intended primarily for
  top-level input to ACL2's read-eval-print loop.</p>

  <p>There are two ways to bypass the check.  Bypass 1 is to construct the
  object in place rather than supply a quoted constant.  This can be as simple
  as consing a @('LAMBDA') onto the rest of your ill-formed constant.  This, of
  course, costs one cons at eval-time.  Bypass 2 is to cons the ill-formed object
  together in a @(tsee defconst) and then use the defined constant symbol in
  the @(':FN') slot.  We illustrate these and other points below.</p>

  @({

  ; Here we show the error that occurs if you use an ill-formed
  ; LAMBDA object in a :FN slot.

  ACL2 !>(apply$ '(lambda (t) (cons t t)) '(a))

  ACL2 Error in TOP-LEVEL: The second element of a well-formed
  LAMBDA object or lambda$ term must be a true list of distinct
  legal variable symbols and (T) is not.  See :DOC
  gratuitous-lambda-object-restrictions for a workaround if you
  really mean to have an ill-formed LAMBDA-like constant in your
  code.  Note: this error occurred in the context
  (APPLY$ '(LAMBDA (T) (CONS T T)) '(A)).

  ; Bypass 1:  Cons the ill-formed object together in place.

  ACL2 !>(apply$ (cons 'lambda '((t) (cons t t))) '(a))
  (A . A)

  ; Bypass 1 (more attractive but perhaps too subtle): Use
  ; backquote.  This looks prettier, indeed, it is almost
  ; unnoticeable!  But it does more eval-time consing.

  ACL2 !>(apply$ `(lambda (t) (cons t t)) '(a))
  (A . A)

  ; Bypass 2:  Use defconst first.  No runtime consing.

  ACL2 !>(defconst *my-ill-formed-lambda*
            `(lambda (t) (cons t t)))
  ...output elided...

  ACL2 !>(apply$ *my-ill-formed-lambda* '(a))
  (A . A)

  ; You can, of course, use these bypasses when defining new
  ; functions.

  ACL2 !>(defun foo (x) (apply$ *my-ill-formed-lambda* (list x)))
  ...successful defun output elided...

  ; You can then execute the new function, possibly slowly.

  ACL2 !>(foo 'b)
  (B . B)

  ; But you can't warrant the new function because defwarrant
  ; can't determine the ilks.

  ACL2 !>(defwarrant foo)

  ACL2 Error in DEFWARRANT: FOO will not be warranted because
  a :FN slot in its body is occupied by a quoted cons object,
  '(LAMBDA (T) (CONS T T)), that is not a well-formed,
  fully-translated, closed ACL2 lambda object. ...

  ; Thus, you can't apply$ 'foo either.

  ACL2 !>(apply$ 'foo '(c))

  ACL2 Error in TOP-LEVEL: The value of APPLY$-USERFN is not
  specified on FOO because FOO has not been warranted.
  })

  <p>By the way, @(':FN') slots are treated differently in another way by
  translate: @(tsee lambda$) terms are <i>only</i> allowed in @(':FN') slots.
  This restriction is necessary for ACL2's correct operation.  @('Lambda$')
  expands differently in the logic than it does in the underlying Common Lisp.
  If @('lambda$') terms were allowed to occur anywhere, this difference could
  be detected by the difference between proved behavior and computed behavior
  and could be used to render ACL2 unsound.</p>")

(defxdoc ground-zero
  :parents (theories theory-functions)
  :short "@(see enable)d rules in the @(see startup) theory"
  :long "<p>ACL2 concludes its initialization @('(boot-strapping)') procedure
 by defining the theory @('ground-zero'); see @(see theories).  In fact, this
 theory is just the theory defined by @('(current-theory :here)') at the
 conclusion of initialization; see @(see current-theory).</p>

 <p>Note that by evaluating the event</p>

 @({
  (in-theory (current-theory 'ground-zero))
 })

 <p>you can restore the current theory to its value at the time you started up
 ACL2.</p>")

(defxdoc gthm
  :parents (history guard-formula-utilities)
  :short "The @(see guard) theorem for a given function symbol"
  :long "<p>This utility (pronounced ``gee-thumb'') generates the @(see guard)
 theorem (i.e., guard proof obligation) for a given function symbol, as would
 be generated by a @(':')@(tsee guard-theorem) @(see lemma-instance) in a
 @(':')@(see use) hint.</p>

 @({
 Example Forms:
 :gthm FN
 (gthm 'FN)              ; equivalent to the above
 (gthm 'FN :limited nil) ; equivalent to the above
 (gthm 'FN :limited t)   ; include guard-debug info
 (gthm 'FN nil)          ; avoid any simplification

 General Forms:
 :gthm FN ; equivalent to (gthm 'FN)
 (gthm x &optional simplify guard-debug)
 })

 <p>where @('FN') is a function symbol and @('x') evaluates to a function
 symbol.  Evaluation returns the guard theorem as a user-level (untranslated)
 @(tsee term).  The optional argument @('simplify'), described below, is
 @(':limited') by default.  The optional argument @('guard-debug') is @('nil')
 by default; when non-@('nil'), the guard theorem is modified as with the
 option @(':guard-debug') for @(tsee verify-guards); see @(see
 guard-debug).</p>

 <p>See @(see lemma-instance) for how to provide the result of @(':gthm') as a
 @(':guard-theorem') prover hint.  Also see @(see guard-formula-utilities) for
 related utilities.</p>

 <p>Normally one will evaluate @(':gthm FN') or equivalently (see @(see
 keyword-commands)), the form @('(gthm 'FN)').  In this case the guard theorem
 may be partially simplified before it is returned, by using a form of
 ``subsumption'' to eliminate redundancy and by deleting tautologies as well as
 instances of @(see built-in-clause) rules that come with ACL2.  The
 @('simplify') argument should be @('nil') to avoid such simplification; that
 is, use @('(gthm 'FN nil)').  See also @(see guard-simplification) for
 discussion of simplification done for various guard formula utilities.</p>

 <p>Note that the result from evaluating @('(gthm x simplify guard-debug)') is
 an <i>untranslated</i> term, that is, a user-level term; see @(see term).
 The corresponding call @('(guard-theorem x simplify guard-debug (w state)
 state)') returns a translated term.</p>")

(defxdoc guarantees-of-the-top-level-loop
  :parents (soundness ld)
  :short "Guarantees provided by top-level evaluation"
  :long "<p>We often refer to the ``top-level loop,'' or just ``the loop'' when
  the context is understood.  The loop is the interactive read-eval-print loop
  with which the user interacts to issue commands, query the ACL2 logical
  world, test functions, conjectures, and systems, etc.  This documentation
  topic mainly addresses the logical guarantees of the loop.  For practical
  advice about interacting with and configuring the loop see @(tsee ld).
  @('Ld') is the ACL2 implementation of the loop (as a macro that calls a
  @(tsee state)-using function with many parameters which may be set by the
  user).  @('Ld') is called initially when ACL2 is fired up.</p>

  <p>But here we are concerned with what it means, logically, when a term
  <i>tm</i> evaluates without error to a value <i>v</i> in the loop.</p>

  <p>We do not formalize macroexpansion here, but rather, we deal with
  so-called &ldquo;translated&rdquo; @(see term)s, where macros and constants
  have been expanded away.  We also do not discuss here how ACL2 evaluates
  expressions; see @(see evaluation) for such discussion.
  (Those interested in implementation issues may also read the long comment in
  ACL2 source file @('interface-raw.lisp') that is labeled &ldquo;Essay on
  Evaluation in ACL2&rdquo;.)</p>

  <p>See @(see soundness) for a more general discussion of soundness-related
  issues (including, for example, interrupts and trust tags).</p>

  <h3>A Strawman Proposal on the Meaning of Top-Level Evaluation</h3>

  <p>One might like to think that for any term, <i>tm</i>, a non-erroneous
  interaction like</p>

  <code>
  ACL2 !&gt;<i>tm</i>
  <i>v</i>
  </code>

  <p>means that the formula</p>

  <code>
  (equal <i>tm</i> '<i>v</i>)
  </code>

  <p>is a theorem and can be proved by the prover.</p>

  <p>For example, let @('sq') be a :logic mode function that squares its
  argument.  (For the sake of a later example, let us also make the @(see
  guard) of @('sq') be @('t') and verify the guard by fixing (with @(tsee
  rfix)) the argument to be a rational, but those aspects of @('sq') are
  irrelevant in our immediate use of it below.)</p>

  <code>
  (defun sq (x)
    (declare (xargs :guard t :verify-guards t))
    (let ((x (rfix x)))
      (* x x)))
  </code>

  <p>then the evaluation</p>

  <code>
  ACL2 !&gt;(sq 3)
  9
  </code>

  <p>suggests that @('(equal (sq 3) 9)') is a theorem and that is indeed
  provable by the ACL2 theorem prover.</p>

  <p>But the situation is quite subtle and deserves further discussion.  That
  is what this topic is about.</p>

  <p><b>Spoiler Alert</b>: We will not give logical semantics to every
  non-erroneous evaluation in this discussion.  We only hint at how it can be
  done for many terms.  Furthermore, even for those terms whose evaluations do
  correspond to theorems, the logical theory in which those theorems can be
  proved is not the theory supported by the ACL2 prover but an extension of it.
  We ultimately describe below the so-called <i>evaluation theory</i> which is
  an extension of ACL2's <i>proof theory</i>.  So this documentation topic
  discusses two logical theories.  Because any theory in which proofs are done
  might be called the ``proof theory'' and in this section we need to clearly
  distinguish between the two theories being discussed, we'll refer to the
  theory supported by the ACL2 theorem prover as the <i>prover's
  theory</i>.</p>

  <h3>Problems Raised by @(':Program') Mode Functions</h3>

  <p>Suppose @('prog-sq') is defined as a @(':')@(tsee program) mode function
  that squares its argument.  Then the top-level evaluation</p>

  <code>
  ACL2 !&gt;(prog-sq 3)
  9
  </code>

  <p>clearly should not suggest</p>

  <code>
  (equal (prog-sq 3) 9)
  </code>

  <p>is a theorem.  @(':Program') mode functions are not defined in the
  prover's theory.  (@(':Program') mode functions may not terminate and any
  naive attempt to add their definitions to the prover's theory as axioms could
  result in unsoundness.)  The top-level loop has the ability to evaluate
  @(':program') mode expressions but it is ``magic,'' unsupported by proof.
  (Non-termination by the evaluator can't manifest unsoundness: such
  computations just never produce an answer.)  The evaluation of @(':program')
  mode expressions is supported in the loop primarily as a way to execute
  commands like @(tsee defun) and @(tsee defthm).  But it is also a convenience
  that allows ACL2 to be used as a @(see programming) language (e.g., to
  prototype a system one might eventually admit to the logic and prove theorems
  about).</p>

  <p>Therefore, when attempting to define the logical meaning of top-level
  evaluations we might restrict our attention to @(':')@(tsee logic) mode terms
  only.  But this is not sufficient for several reasons.</p>

  <p>@(':Program') mode functions raise another problem discussed below in
  connection with @('apply$').</p>

  <h3>Problems Raised by Single-Threaded Objects</h3>

  <p>Evaluation of terms involving single-threaded objects or ``@(see stobj)s''
  raise problems, even if the terms involved are in @(':logic') mode.  Here is
  a top-level evaluation sequence</p>

  <code>
  ACL2 !&gt;(defstobj st fld)
  ...
  ST
  ACL2 !&gt;(update-fld 3 st)
  &lt;st&gt;
  ACL2 !&gt;(update-fld (sq (fld st)) st)
  &lt;st&gt;
  ACL2 !&gt;(fld st)
  9
  </code>

  <p>but the strawman conjecture from the last evaluation, @('(equal (fld st)
  9)'), is not a theorem.  However, a related formula is a theorem and can be
  proved by the prover.</p>

  <code>
  (implies (stp st)
           (let* ((st (update-fld 3 st))
                  (st (update-fld (sq (fld st)) st)))
             (equal (fld st) 3)))
  </code>

  <p>This reminds us that the top-level loop tracks changes to each ``live''
  stobj and records them in the ACL2 @(tsee state).  Those changes must be
  reflected in any suggested theorems.</p>

  <h3>Problems Raised by Apply$</h3>

  <p>@(tsee Apply$) calls @(tsee apply$-userfn) to handle the application of
  user-defined function symbols.  @('Apply$-userfn') is undefined but might be
  constrained by @(tsee warrant) hypotheses (see @(tsee defwarrant)).  Recall
  that warrants link the functions approved by @('defwarrant') to their names
  and constrain @('(apply$ 'fn (list a1 ... an))') to be @('(fn a1 ... an)')
  under certain @(tsee tame)ness conditions.  As noted at the bottom of the
  discussion of @(tsee defwarrant), there is a model of the prover's theory in
  which all warrants issued by @('defwarrant') are true.  The top-level loop
  assumes that all those warrants are true.  But the prover's theory does not,
  because explicit warrant hypotheses are essential to avoiding the so-called
  ``local problem'' (see <b>Lesson 12</b> of @(see
  introduction-to-apply$)).</p>

  <p>One might wonder why we have warrants at all, aside from the local
  problem.  The key reason is that inconsistency can result from
  non-terminating recursion if we had the following
  axiom schema</p>

  <code>
  <b>Unsound Axiom Schema</b>:
  (equal (apply$ '<i>f</i> (list a1 ... an)) (<i>f</i> a1 ... an))
  </code>

  <p>for every defined function <i>f</i>.  See the @('russell') example in
  @(see introduction-to-apply$).  So warrants and the restrictions enforced by
  @(tsee defwarrant) keep the prover's theory consistent.  One might then ask
  ``how do we get away with letting the top-level loop @('apply$') all badged
  @(':program') mode functions?''  The answer is simple: @(':program') mode
  functions are not axiomatized so we don't have a theory to worry about!</p>

  <p>To illustrate the difference between the behavior of the top-level loop
  and the prover, suppose the function @('sq'), defined above, has been
  warranted.</p>

  <code>
  (defwarrant sq)
  </code>

  <p>and then consider the top-level evaluation</p>

  <code>
  ACL2 !&gt;(apply$ 'sq '(3))
  9
  </code>

  <p>This is possible because the warrant for @('sq') is assumed true in the
  top-level loop and that warrant tells the loop that @('(apply$ 'sq '(3))') =
  @('(sq 3)').</p>

  <p>However, @('(equal (apply$ 'sq '(3)) '9)') is not a theorem in the
  prover's theory.  Instead, this is a theorem</p>

  <code>
  (implies (warrant sq)
           (equal (apply$ 'sq '(3)) '9))
  </code>

  <p>where @('(warrant sq)') is just a convenient abbreviation for
  @('(force (apply$-warrant-sq))').</p>

  <p>Thus, to extend the strawman conjecture to functions in which @('apply$')
  is ancestral would require tracking the warrants relevant to the execution
  path (or punting and collecting all warrants) and amending the conjecture to
  add those warrants as hypotheses to the equality.</p>

  <p>But @('apply$') introduces another source of complexity: mixed-mode
  functions (see @(see mixed-mode-functions)).  Recall the @(':program') mode
  function @('prog-sq') which squares its argument.  We can assign a badge to
  @('prog-sq') and then define a @(':logic') mode function that @('apply$')s
  it!</p>

  <code>
  (defbadge prog-sq)

  (defun logic-sq (x)
    (declare (xargs :mode :logic))
    (apply$ 'prog-sq (list x)))
  </code>

  <p>Since the top-level loop can evaluate applications of @(':program') mode
  symbols we see the following evaluation.</p>

  <code>
  ACL2 !&gt;(logic-sq 3)
  9
  </code>

  <p>Note that @('(logic-sq 3)') is a @(':logic') mode term and @('logic-sq')
  can even be warranted with @('defwarrant').  But neither</p>

  <code>
  (equal (logic-sq 3) '9)
  </code>

  <p>nor</p>

  <code>
  (implies (warrant logic-sq) (equal (logic-sq 3) '9))
  </code>

  <p>is a theorem in the prover's theory because @('prog-sq') is undefined in
  that theory.  For what it is worth, the prover can prove</p>

  <code>
  (implies (warrant logic-sq) (equal (logic-sq 3) (apply$ 'prog-sq '(3))))
  </code>

  <p>This example contradicts the suggestion, just above, that if we properly
  considered warrants we could give logical meaning to evaluations of
  @(':logic') mode terms involving @('apply$').</p>

  <h3>Problems Raised by Constrained Functions</h3>

  <p>Constrained functions raise problems if they have been given
  attachments (see @(tsee defattach)).  The top-level loop uses attachments to
  compute values consistent with the constraints, but the prover's theory does
  not.  Attachments are useful for building and testing instances of models
  consistent with the constraints.</p>

  <p>For example, let @('(nonneg-rat x)') be constrained to return some
  nonnegative rational.</p>

  <code>
  (encapsulate (((nonneg-rat *) =&gt; *))
    (local (defun nonneg-rat (x)
             (declare (ignore x))
             0))
    (defthm nonneg-rat-constraint
      (and (rationalp (nonneg-rat x))
           (&lt;= 0 (nonneg-rat x)))))
  </code>

  <p>It is impossible to evaluate @('(nonneg-rat 3)') in the top-level loop.
  But we can attach another function to it provided we can prove that function
  always returns a nonnegative rational.  Since @('sq'), as defined above to
  @('rfix') its argument as a rational, satisfies that constraint, we can attach
  @('sq') to @('nonneg-rat').</p>

  <code>
  (defattach nonneg-rat sq)
  </code>

  <p>and then we can ``evaluate'' calls of @('nonneg-rat') in the loop, getting
  results that are consistent with its constraint (but overly specific!).</p>

  <code>
  ACL2 !&gt;(nonneg-rat 3)
  9
  </code>

  <p>But of course the strawman conjecture @('(equal (nonneg-rat 3) '9)') is
  not a theorem of the prover's theory.</p>

  <h3>The Prover's Theory</h3>

  <p>The ACL2 logic formalizes an applicative (functional and side-effect free)
  extension of a subset of Common Lisp (see @(see common-lisp)).  It is
  described in chapter 6 of <a
  href='http://www.cs.utexas.edu/users/moore/publications/acl2-books/car/index.html'>Computer-Aided
  Reasoning: An Approach</a>, by Kaufmann, Manolios, and Moore, as an extension
  of quantifier-free first-order logic with equality (section 6.1).  The syntax
  is that of translated @(see term)s though the user is allowed to use a more
  flexible syntax which can be extended by defining constant symbols and
  macros (see @(tsee defconst) and @(tsee defmacro)).  To see the formal
  translation of such a term use the command @(':')@(tsee trans).  In section
  6.2 of the book, axioms are added to characterize the basic data objects of
  numbers (integers, rationals, and complex rationals), characters, strings,
  symbols, and ordered pairs.  In section 6.3, the ordinals up to epsilon-0 are
  constructed from ordered pairs and integers; a well-founded ``less than''
  relation is also defined.  But the book's construction of the ordinals is now
  obsolete.  A new representation was implemented after the book was published.
  See @(see ordinals).  In Section 6.4, a conservative Principle of
  Definition (see @(tsee defun) and @(tsee defuns) or @(tsee mutual-recursion))
  is introduced, allowing the addition of axioms defining new function symbols.
  In Section 6.5, a Principle of Induction up to epsilon-0 is described.
  Induction and recursion are duals: every admissible recursive function
  suggests an induction and vice versa and this duality is used by the ACL2
  prover to select an often appropriate induction scheme for a conjecture.  See
  @(see induction) and @(tsee hints) for ways to influence this selection.
  Finally, in section 6.6, the book introduces @(tsee encapsulate) to introduce
  constrained functions and functional instantiation (a derived rule of
  inference akin to second order instantiation), and a variety of other ways of
  conservatively adding new function symbols.</p>

  <p>The ACL2 prover proves theorems in the extension of the above theory
  obtained by adding the axioms introduced by @(see events) successfully
  carried out in the user's session.  The most common such axiom-adding events
  are @(tsee defun), @(tsee defchoose), and @(tsee encapsulate), which all
  conservatively extend the theory by the addition of axioms about new function
  symbols.  But @('defun') is just a special case of @('defuns') which adds a
  mutually recursive clique of new names (see also @(tsee mutual-recursion)).
  @(tsee Defstobj) and @(tsee defabsstobj) add recognizers, constructors, and
  accessors for single-threaded objects (aka ``@(see stobj)s'') but logically
  just use @('defun') to add new functions and then syntactically restrict
  their use in code.  Finally, we provide a means of adding an arbitrary
  formula as an axiom, @(tsee defaxiom), but <i>strongly discourage its
  use</i>.  There are many other events that add axioms, e.g., @(tsee defun-nx)
  and @(tsee defun-sk) but these are defined as macros that expand into the
  primitives just listed.  In addition, there is a facility for including files
  of previously admitted events, @(tsee include-book).</p>

  <p>Note that an event of the form @('(skip-proofs EV)') does not introduce
  any axioms other that those added by the event, @('EV').  However, this
  @(tsee skip-proofs) event does assume that all proof obligations introduced
  by @('EV') are indeed provable in the prover's theory.</p>

  <p>Given a user's session, we call the above described theory the <i>prover's
  theory</i>.</p>

  <p>Now recall the strawman proposal for what evaluation in the top-level loop
  means, i.e., that the evaluation</p>

  <code>
  ACL2 !&gt;<i>tm</i>
  <i>v</i>
  </code>

  <p>might mean that the formula</p>

  <code>
  (equal <i>tm</i> '<i>v</i>)
  </code>

  <p>is a theorem.  We have illustrated with @(':program') mode functions, uses
  of @('apply$'), and of constrained functions that this strawman conjecture is
  <i>not</i> necessarily a theorem of the prover's theory!</p>

  <p>However, there is a theory in which many of these conjectures are
  theorems.</p>

  <h3>The Evaluation Theory</h3>

  <p>The <i>evaluation theory</i> is obtained from the prover's theory as
  follows.</p>

  <ul>

  <li>Instead of treating stobj names as variables, the evaluation theory
  treats them as abbreviations for the ``current value'' of the stobj,
  specifically, the constant obtained by composing the sequence of all updates
  to the stobj's fields carried out so far in the top-level loop.  Thus, for
  example, in the evaluation theories created by this sequence of top-level
  evaluations

  <code>
  ACL2 !&gt;(defstobj st fld)                           ; [1]
  ST
  ACL2 !&gt;(update-fld 3 st)                           ; [2]
  &lt;st&gt;
  ACL2 !&gt;(update-fld (* (fld st) (fld st)) st)       ; [3]
  &lt;st&gt;
  </code>

  @('st') is an abbreviation for @('(NIL)') after evaluation [1], an
  abbreviation for @('(3)') after evaluation [2], and an abbreviation for
  @('(9)') after evaluation [3].</li>

  <li>Every warrant created by @('defwarrant') is assumed true as an
  axiom.</li>

  <li>For every @('(defattach f g)') event in the prover's theory the
  axiom (i.e., constraints) on @('f') is replaced by the axiom @('(equal (f
  ...) (g ...))') in the evaluation theory.  (Of course this replacement also
  takes place when using the more general form for @(tsee defattach),
  @('(defattach ... (f g ...) ...)').)</li>

  </ul>

  <p>Given the restrictions enforced by @('defun'), @('defstobj'),
  @('defwarrant'), @('apply$'), @('encapsulate'), and @('defattach'), the
  evaluation theory is consistent if the prover's theory is consistent and free
  of @('defaxiom') events.  (Those interested in reading a proof of this claim
  are welcome to read the &ldquo;Essay on Defattach&rdquo; in ACL2 source file
  @('other-events.lisp').)</p>

  <p>Furthermore, the top-level evaluation</p>

  <code>
  ACL2 !&gt;<i>tm</i>
  <i>v</i>
  </code>

  <p>means that</p>

  <code>
  (equal <i>tm</i> '<i>v</i>)
  </code>

  <p>is a theorem in the evaluation theory provided</p>

  <ul>

  <li><i>tm</i> is a @(':logic') mode term, and</li>

  <li>every symbol that reaches the first argument of any @('apply$-userfn') in
  the execution of <i>tm</i> is in @(':logic') mode.</li>

  </ul>

  <p>The ACL2 prover cannot generally prove these theorems, since it operates
  in the prover's theory.  However, as noted, there are often ways to encode
  the conjectures into ACL2 formulas that are provable &mdash; in particular,
  by adding suitable warrant hypotheses &mdash; though the ACL2 system does not
  provide tools for doing so.</p>

  <h3>Some Examples of Top-Level Evaluations</h3>

  <p>In this section we illustrate some consequences of the guarantee that for
  any term, <i>tm</i>, satisfying certain restrictions, if <i>tm</i> evaluates
  to a value <i>v</i>, then the term</p>

  <code>
  (equal <i>tm</i> '<i>v</i>)
  </code>

  <p>is a theorem of the evaluation theory.</p>

  <p>Each command below is enumerated and after the entire sequence we make
  observations about the results and implications.  It might also help to read
  the section <b>Top-Level Evaluation of Apply$</b> in the documentation for
  @(tsee apply$), which describes how @('apply$') is implemented in the
  top-level loop.</p>

  @({
  ACL2 !>(include-book "projects/apply/top" :dir :system)
  ...
  ACL2 !>(defun my-cons (x y)                                  ; [1]
            (declare (xargs :mode :program))
            (cons x y))
  ...
  ACL2 !>(defbadge my-cons)                                    ; [2]

  MY-CONS now has the badge (APPLY$-BADGE 2 1 . T) but has
  no warrant.

   T
  ACL2 !>(apply$ 'my-cons '(3 4))                              ; [3]
  (3 . 4)
  ACL2 !>(thm (equal (my-cons 3 4) '(3 . 4)))                  ; [4]
  ...
  ******** FAILED ********
  ACL2 !>(verify-termination my-cons)                          ; [5]
  ...
  ACL2 !>(apply$ 'my-cons '(3 4))                              ; [6]


  ACL2 Error in TOP-LEVEL:  The value of APPLY$-USERFN is not
   specified on MY-CONS because MY-CONS has not been warranted.

  ACL2 !>(defwarrant my-cons)                                  ; [7]

  MY-CONS is now warranted by APPLY$-WARRANT-MY-CONS, with
  badge (APPLY$-BADGE 2 1 . T).

  ACL2 !>(apply$ 'my-cons '(3 4))                              ; [8]
  (3 . 4)

  ACL2 !>ACL2 !>(thm (equal (my-cons 3 4) '(3 . 4)))           ; [9]
  ...
  ******** FAILED ********
  ACL2 !>(thm                                                  ;[10]
          (implies (warrant my-cons)
                   (equal (my-cons 3 4) '(3 . 4))))
  ...
  Q.E.D.
  ...
  Proof succeeded.
  })

  <p>In events [1] and [2] @('my-cons') is introduced as a badged @(':program')
  mode function.  Command [3] shows that we can @('apply$') @(''my-cons') in
  the top-level loop and get the ``expected'' value.  This is ``magic'' on
  several levels!  There is no axiom in the evaluation theory defining
  @('my-cons') and there is no warrant connecting the symbol @(''my-cons') to
  the function @('my-cons').  The failure of the first @('thm') command, [4],
  shows that the prover's theory knows nothing of the behavior of @('apply$')
  on @(''my-cons').  After converting @('my-cons') to @(':logic') mode with
  @(tsee verify-termination) in [5] we can no longer evaluate the application
  of @('my-cons') at the top-level, as shown by [6]!  This is surprising
  because one might expect ACL2 to be able to do more with a @(':logic') mode
  function than its @(':program') mode counterpart.  But in the evolving
  evaluation theory as of [6], @('my-cons') is a @(':logic') mode function with
  no warrant and so logically speaking @('(apply$ 'my-cons ...)')  is
  undefined.  Computing a value for it at [6] would violate the guarantee that
  values of @(':logic') mode terms can be proved correct in the evaluation
  theory &mdash; i.e., that the computed value can be derived logically.  Such
  a derivation is impossible without a warrant.  However, after
  @('defwarrant'), in [7], confirms that it is sound to issue a
  warrant (linking the symbol @(''my-cons') to the function @('my-cons') via
  @('apply$')), the evaluation of the @(''my-cons') term in [8] succeeds.  The
  @('defwarrant') soundly extends the proof theory by adding a definition for
  the warrant function for @('my-cons') and extends the evaluation theory by
  assuming the warrant for @('my-cons') is true.  This latter extension is also
  sound.  However, [9] shows that we still cannot prove (in the prover's
  theory) that the evaluation of the @('apply$') term is correct, because we
  did not provide the warrant as a hypothesis.  However, if we amend the
  conjecture to include the warrant, as in [10], the proof (in the prover's
  theory) succeeds.  While all warrants are assumed true in the evaluation
  theory, they must be made explicit as hypotheses for proofs in the prover's
  theory.  This is the mechanism whereby ACL2 can avoid the ``local problem''
  illustrated in <b>Lesson 12</b> of @(see introduction-to-apply$) and
  discussed more thoroughly in <a
  href='http://www.cs.utexas.edu/users/kaufmann/papers/apply/index.html'>``Limited
  Second-Order Functionality in a First-Order Setting''</a> by Matt Kaufmann
  and J Strother Moore.</p>")

(defxdoc guard
  :parents (programming xargs)
  :short "Restricting the domain of a function"
  :long "<p>NOTE: Novices are often best served by avoiding guards.</p>

 <p>The ACL2 system provides a mechanism for restricting a function to a
 particular domain.  Such restrictions are called ``guards.''  A definition's
 guard has no effect on the logical axiom added when that definition is
 accepted by ACL2.  Moreover, the guard has NO EFFECT on the proof that a
 recursive definition is admissible &mdash; informally, that it terminates).
 (See @(see mbt) for a discussion of one way to use the guard explicitly to
 assist with that proof while avoiding execution overhead.)</p>

 <p>Guards can be useful as a specification device or for increasing execution
 efficiency.  To make such a restriction, use the @(':guard') keyword (see
 @(see xargs)) or, especially if you want the host Lisp compiler to use this
 information, use @('type') declarations (see @(see declare); also see @(see
 xargs) for a discussion of the @(':split-types') keyword).  The general issue
 of guards and guard verification is discussed in the topics listed below.</p>

 <p>To begin further discussion of guards, see @(see guard-introduction).  That
 section directs the reader to further sections for more details.  To see just
 a summary of some @(see command)s related to guards, see @(see
 guard-quick-reference).  For a discussion of the use of proof to verify the
 absence of guard violations, see @(see verify-guards).</p>")

(defxdoc guard-checking-inhibited
  :parents (evaluation guard)
  :short "Avoiding certain warnings when evaluating ACL2 expressions"
  :long "<p>ACL2 sometimes omits the checking of @(see guard)s on recursive
 calls of functions.  This omission is signaled by a warning like the one shown
 below.</p>

 @({
 ACL2 !>(factorial 3)

 ACL2 Warning [Guards] in TOP-LEVEL:  Guard-checking will be inhibited
 for some recursive calls for FACTORIAL and perhaps other functions;
 see :DOC guard-checking-inhibited.

 6
 ACL2 !>
 })

 <p>This behavior can occur for a recursively-defined @(see logic)-mode
 function with a guard other than @('t') whose guards have not been verified,
 when @(see guard-checking) has its default value, @('t').  (Exceptions may
 occur, for example when the function is being traced.)  No further such
 message is printed (for any function) before the next top-level form is
 submitted.</p>

 <p>To check guards on all recursive calls:</p>

 @({
 (set-guard-checking :all)
 })

 <p>To leave the current behavior unchanged except for inhibiting such
 messages:</p>

 @({
 (set-guard-checking :nowarn)
 })")

(defxdoc guard-debug
  :parents (guard debugging)
  :short "Generate markers to indicate sources of @(see guard) proof obligations"
  :long "<p>ACL2 guard verification (see @(see guard)) is often best avoided by
 beginning users of ACL2.  When guard verification is employed, it can generate
 numerous goals, some of which may not be theorems if the definition being
 processed has bugs.  It can be difficult to find such bugs.  This @(see
 documentation) topic explains a capability provided by ACL2 to help find such
 bugs.</p>

 <p>For a similar utility appropriate for proving @(see measure) conjectures
 (that is, for termination proofs), see @(see measure-debug).</p>

 <p>We begin with the following example.  Although it is contrived and a bit
 simplistic, it illustrates how the guard-debug utility works.</p>

 @({
  (defun length-repeat (x)
    (length (append x x)))
  (verify-guards length-repeat :guard-debug t)
 })

 <p>The output produces two top-level key checkpoints, as follows.</p>

 @({
  Subgoal 2
  (IMPLIES (EXTRA-INFO '(:GUARD (:BODY LENGTH-REPEAT))
                       '(APPEND X X))
           (TRUE-LISTP X))

  Subgoal 1
  (IMPLIES (AND (EXTRA-INFO '(:GUARD (:BODY LENGTH-REPEAT))
                            '(LENGTH (APPEND X X)))
                (NOT (TRUE-LISTP (APPEND X X))))
           (STRINGP (APPEND X X)))
 })

 <p>The upper subgoal (numbered 2) says that the body of the definition of
 @('length-repeat') contains a call @('(APPEND X X)'), which is the source of
 the goal.  In this case, that makes sense: the @(see guard) for a call
 @('(append arg1 arg2)') is @('(true-listp arg1)'), which in this case is
 @('(TRUE-LISTP X)').  The lower subgoal (numbered 1) says that the same
 definition contains the call @('(LENGTH (APPEND X X))'), which generates the
 proof obligation that if @('(APPEND X X)') does not satisfy @('true-listp'),
 then it must satisfy @('stringp').  That proof obligation comes directly from
 the @(see guard) for @(tsee length).</p>

 <p>Of course, the example above is a bit obvious.  But for large definitional
 bodies such information can be very helpful.  Note that guard-debug can be
 specified not only in @(tsee verify-guards) events but also in @(tsee xargs)
 @(tsee declare) forms of @(tsee defun) events.</p>

 <p>We now describe the guard-debug utility in some detail.</p>

 <p>@('(Extra-info x y)') always returns @('t') by definition.  However, if
 @(see guard) verification takes place with a non-@('nil') setting of
 @('guard-debug') (see below), then the goals generated for guard verification
 can include hypotheses that are calls of @('extra-info').  Typically, such a
 hypothesis is of the following form:</p>

 @({
  (extra-info '(:guard (:body F))
              '(G ARG1 ... ARGk))
 })

 <p>The above form indicates that the goal in which it occurs was generated to
 verify that the @(see guard) of the function @('F') is satisfied by the
 arguments @('ARG1') through @('ARGk'), where the term @('(G ARG1 ... ARGk)')
 occurs in the body of the function @('F') whose guard verification is in
 progress.  If however the above call of @('G') occurs in the guard of @('F')
 instead of the body of @('F'), then @(':body') is replaced by @(':guard')
 above:</p>

 @({
  (extra-info '(:guard (:guard F))
              '(G ARG1 ... ARGk))
 })

 <p>If the same proof obligation (goal @(see clause)) arises from more than one
 occurrence of the same call, then a single goal will be generated, which has
 several @('extra-info') hypotheses added to show the multiple sources of that
 proof obligation.</p>

 <p>All rules (see @(see rune)) associated with @('extra-info') are @(see
 disable)d by default, so that hypotheses of the form described above are not
 simplified to @('t').  These hypotheses are intended to ride along for free:
 you can generally expect the proof to have the same structure whether or not
 the @(':guard-debug') option is supplied, though on rare occasions the proofs
 may diverge.</p>

 <p>It remains to explain the notion of a @('guard-debug') setting of @('t'),
 that is, to explain how to obtain the additional hypotheses described above.
 If guards are being verified during processing of a @(tsee defun) event
 (whether or not inside a call of @(tsee mutual-recursion)), then one specifies
 @(':guard-debug t') in an @(tsee xargs) declaration of a @(tsee declare) form;
 see @(see xargs).  If however the guard verification is on behalf of a @(tsee
 verify-guards) call, whether for a definition or a theorem, then one specifies
 the keyword argument @(':guard-debug t').</p>

 <p>Also see @(see print-gv) for a utility for debugging guard violations, in
 contrast to the above guard-debug mechanism, which is for debugging failed
 proofs arising from guard verification.</p>")

(defxdoc guard-evaluation-examples-log
  :parents (guard)
  :short "Log showing combinations of @(see defun-mode)s and @(see
 guard)-checking"
  :long "<p>See @(see guard-evaluation-examples-script) for a script that shows
 the interaction of @(see defun-mode)s with the value set by @(tsee
 set-guard-checking).  Here, we present a log resulting from running this
 script.  It may also be helpful to see @(see evaluation).</p>

 <p>See @(see set-guard-checking) for discussion of the interaction between
 @(see defun-mode)s and @(see guard)-checking that is illustrated by this
 script.  Also see @(see guard-evaluation-table) for a succinct table, with
 associated discussion, that covers in detail the interactions illustrated
 here.</p>

 @({
  ACL2 !>(defun fact (x)
           (declare (xargs :guard (integerp x)
                           :mode :program))
           (if (posp x)
               (* x (fact (1- x)))
             1))

  Summary
  Form:  ( DEFUN FACT ...)
  Rules: NIL
  Warnings:  None
  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
   FACT
  ACL2 !>(trace$ fact)
   ((FACT))
  ACL2 !>:set-guard-checking t

  Guard-checking-on already has value T.

  ACL2 !>(fact 2)
  1> (ACL2_*1*_ACL2::FACT 2)
    2> (FACT 2)
      3> (FACT 1)
        4> (FACT 0)
        <4 (FACT 1)
      <3 (FACT 1)
    <2 (FACT 2)
  <1 (ACL2_*1*_ACL2::FACT 2)
  2
  ACL2 !>(fact t)
  1> (ACL2_*1*_ACL2::FACT T)

  ACL2 Error in TOP-LEVEL:  The guard for the :program function symbol
  FACT, which is (INTEGERP X), is violated by the arguments in the call
  (FACT T).  See :DOC trace for a useful debugging utility.  See :DOC
  set-guard-checking for information about suppressing this check with
  (set-guard-checking :none), as recommended for new users.

  ACL2 !>:set-guard-checking :all

  Leaving guard checking on, but changing value to :ALL.

  ACL2 !>(fact 2)
  1> (ACL2_*1*_ACL2::FACT 2)
    2> (ACL2_*1*_ACL2::FACT 1)
      3> (ACL2_*1*_ACL2::FACT 0)
      <3 (ACL2_*1*_ACL2::FACT 1)
    <2 (ACL2_*1*_ACL2::FACT 1)
  <1 (ACL2_*1*_ACL2::FACT 2)
  2
  ACL2 !>(fact t)
  1> (ACL2_*1*_ACL2::FACT T)

  ACL2 Error in TOP-LEVEL:  The guard for the :program function symbol
  FACT, which is (INTEGERP X), is violated by the arguments in the call
  (FACT T).  See :DOC trace for a useful debugging utility.  See :DOC
  set-guard-checking for information about suppressing this check with
  (set-guard-checking :none), as recommended for new users.

  ACL2 !>:set-guard-checking :none

  Turning off guard checking entirely.  To allow execution in raw Lisp
  for functions with guards other than T, while continuing to mask guard
  violations, :SET-GUARD-CHECKING NIL.  See :DOC set-guard-checking.

  ACL2 >(fact 2)
  1> (ACL2_*1*_ACL2::FACT 2)
    2> (ACL2_*1*_ACL2::FACT 1)
      3> (ACL2_*1*_ACL2::FACT 0)
      <3 (ACL2_*1*_ACL2::FACT 1)
    <2 (ACL2_*1*_ACL2::FACT 1)
  <1 (ACL2_*1*_ACL2::FACT 2)
  2
  ACL2 >(fact t)
  1> (ACL2_*1*_ACL2::FACT T)
  <1 (ACL2_*1*_ACL2::FACT 1)
  1
  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 >(fact 2)
  1> (ACL2_*1*_ACL2::FACT 2)
    2> (FACT 2)
      3> (FACT 1)
        4> (FACT 0)
        <4 (FACT 1)
      <3 (FACT 1)
    <2 (FACT 2)
  <1 (ACL2_*1*_ACL2::FACT 2)
  2
  ACL2 >(fact t)
  1> (ACL2_*1*_ACL2::FACT T)
    2> (FACT T)
    <2 (FACT 1)
  <1 (ACL2_*1*_ACL2::FACT 1)
  1
  ACL2 >:u

            0:x(EXIT-BOOT-STRAP-MODE)
  ACL2 >(defun fact (x)
           (declare (xargs :guard t
                           :mode :program))
           (if (posp x)
               (* x (fact (1- x)))
             1))

  Summary
  Form:  ( DEFUN FACT ...)
  Rules: NIL
  Warnings:  None
  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
   FACT
  ACL2 >(trace$ fact)
   ((FACT))
  ACL2 >:set-guard-checking t

  Turning guard checking on, value T.

  ACL2 !>(fact 2)
  1> (ACL2_*1*_ACL2::FACT 2)
    2> (FACT 2)
      3> (FACT 1)
        4> (FACT 0)
        <4 (FACT 1)
      <3 (FACT 1)
    <2 (FACT 2)
  <1 (ACL2_*1*_ACL2::FACT 2)
  2
  ACL2 !>(fact t)
  1> (ACL2_*1*_ACL2::FACT T)
    2> (FACT T)
    <2 (FACT 1)
  <1 (ACL2_*1*_ACL2::FACT 1)
  1
  ACL2 !>:set-guard-checking :all

  Leaving guard checking on, but changing value to :ALL.

  ACL2 !>(fact 2)
  1> (ACL2_*1*_ACL2::FACT 2)
    2> (ACL2_*1*_ACL2::FACT 1)
      3> (ACL2_*1*_ACL2::FACT 0)
      <3 (ACL2_*1*_ACL2::FACT 1)
    <2 (ACL2_*1*_ACL2::FACT 1)
  <1 (ACL2_*1*_ACL2::FACT 2)
  2
  ACL2 !>(fact t)
  1> (ACL2_*1*_ACL2::FACT T)
  <1 (ACL2_*1*_ACL2::FACT 1)
  1
  ACL2 !>:set-guard-checking :none

  Turning off guard checking entirely.  To allow execution in raw Lisp
  for functions with guards other than T, while continuing to mask guard
  violations, :SET-GUARD-CHECKING NIL.  See :DOC set-guard-checking.

  ACL2 >(fact 2)
  1> (ACL2_*1*_ACL2::FACT 2)
    2> (ACL2_*1*_ACL2::FACT 1)
      3> (ACL2_*1*_ACL2::FACT 0)
      <3 (ACL2_*1*_ACL2::FACT 1)
    <2 (ACL2_*1*_ACL2::FACT 1)
  <1 (ACL2_*1*_ACL2::FACT 2)
  2
  ACL2 >(fact t)
  1> (ACL2_*1*_ACL2::FACT T)
  <1 (ACL2_*1*_ACL2::FACT 1)
  1
  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 >(fact 2)
  1> (ACL2_*1*_ACL2::FACT 2)
    2> (FACT 2)
      3> (FACT 1)
        4> (FACT 0)
        <4 (FACT 1)
      <3 (FACT 1)
    <2 (FACT 2)
  <1 (ACL2_*1*_ACL2::FACT 2)
  2
  ACL2 >(fact t)
  1> (ACL2_*1*_ACL2::FACT T)
    2> (FACT T)
    <2 (FACT 1)
  <1 (ACL2_*1*_ACL2::FACT 1)
  1
  ACL2 >:u

            0:x(EXIT-BOOT-STRAP-MODE)
  ACL2 >(defun fact (x)
           (declare (xargs :guard (integerp x)
                           :verify-guards nil
                           :mode :logic))
           (if (posp x)
               (* x (fact (1- x)))
             1))

  For the admission of FACT we will use the relation O< (which is known
  to be well-founded on the domain recognized by O-P) and the measure
  (ACL2-COUNT X).  The non-trivial part of the measure conjecture is

  [[output omitted here]]

  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
   FACT
  ACL2 >(trace$ fact)
   ((FACT))
  ACL2 >:set-guard-checking t

  Turning guard checking on, value T.

  ACL2 !>(fact 2)
  [[Comment added to the log:
    Normally you would get a message about guard-checking being
    inhibited on recursive calls.  However, when a function is
    traced the guard-checking is done on recursive calls unless
    the guards have been verified (see :DOC verify-guards).
  ]]
  1> (ACL2_*1*_ACL2::FACT 2)
    2> (ACL2_*1*_ACL2::FACT 1)
      3> (ACL2_*1*_ACL2::FACT 0)
      <3 (ACL2_*1*_ACL2::FACT 1)
    <2 (ACL2_*1*_ACL2::FACT 1)
  <1 (ACL2_*1*_ACL2::FACT 2)
  2
  ACL2 !>(fact t)
  1> (ACL2_*1*_ACL2::FACT T)

  ACL2 Error in TOP-LEVEL:  The guard for the function symbol FACT, which
  is (INTEGERP X), is violated by the arguments in the call (FACT T).
  See :DOC trace for a useful debugging utility.  See :DOC set-guard-
  checking for information about suppressing this check with (set-guard-
  checking :none), as recommended for new users.

  ACL2 !>:set-guard-checking :all

  Leaving guard checking on, but changing value to :ALL.

  ACL2 !>(fact 2)
  1> (ACL2_*1*_ACL2::FACT 2)
    2> (ACL2_*1*_ACL2::FACT 1)
      3> (ACL2_*1*_ACL2::FACT 0)
      <3 (ACL2_*1*_ACL2::FACT 1)
    <2 (ACL2_*1*_ACL2::FACT 1)
  <1 (ACL2_*1*_ACL2::FACT 2)
  2
  ACL2 !>(fact t)
  1> (ACL2_*1*_ACL2::FACT T)

  ACL2 Error in TOP-LEVEL:  The guard for the function symbol FACT, which
  is (INTEGERP X), is violated by the arguments in the call (FACT T).
  See :DOC trace for a useful debugging utility.  See :DOC set-guard-
  checking for information about suppressing this check with (set-guard-
  checking :none), as recommended for new users.

  ACL2 !>:set-guard-checking :none

  Turning off guard checking entirely.  To allow execution in raw Lisp
  for functions with guards other than T, while continuing to mask guard
  violations, :SET-GUARD-CHECKING NIL.  See :DOC set-guard-checking.

  ACL2 >(fact 2)
  1> (ACL2_*1*_ACL2::FACT 2)
    2> (ACL2_*1*_ACL2::FACT 1)
      3> (ACL2_*1*_ACL2::FACT 0)
      <3 (ACL2_*1*_ACL2::FACT 1)
    <2 (ACL2_*1*_ACL2::FACT 1)
  <1 (ACL2_*1*_ACL2::FACT 2)
  2
  ACL2 >(fact t)
  1> (ACL2_*1*_ACL2::FACT T)
  <1 (ACL2_*1*_ACL2::FACT 1)
  1
  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 >(fact 2)
  [[Comment added to the log:
    In spite of the warning above, guards are checked here on
    self-recursive calls, because the function is traced.
  ]]
  1> (ACL2_*1*_ACL2::FACT 2)
    2> (ACL2_*1*_ACL2::FACT 1)
      3> (ACL2_*1*_ACL2::FACT 0)
      <3 (ACL2_*1*_ACL2::FACT 1)
    <2 (ACL2_*1*_ACL2::FACT 1)
  <1 (ACL2_*1*_ACL2::FACT 2)
  2
  ACL2 >(fact t)
  1> (ACL2_*1*_ACL2::FACT T)
  <1 (ACL2_*1*_ACL2::FACT 1)
  1
  ACL2 >(verify-guards fact)

  Computing the guard conjecture for FACT....

  The guard conjecture for FACT is trivial to prove, given the :compound-
  recognizer rule POSP-COMPOUND-RECOGNIZER, primitive type reasoning
  and the :type-prescription rule FACT.  FACT is compliant with Common
  Lisp.

  Summary
  Form:  ( VERIFY-GUARDS FACT)
  Rules: ((:COMPOUND-RECOGNIZER POSP-COMPOUND-RECOGNIZER)
          (:FAKE-RUNE-FOR-TYPE-SET NIL)
          (:TYPE-PRESCRIPTION FACT))
  Warnings:  None
  Time:  0.01 seconds (prove: 0.00, print: 0.00, other: 0.01)
   FACT
  ACL2 >(trace$ fact)
   ((FACT))
  ACL2 >:set-guard-checking t

  Turning guard checking on, value T.

  ACL2 !>(fact 2)
  1> (ACL2_*1*_ACL2::FACT 2)
    2> (FACT 2)
      3> (FACT 1)
        4> (FACT 0)
        <4 (FACT 1)
      <3 (FACT 1)
    <2 (FACT 2)
  <1 (ACL2_*1*_ACL2::FACT 2)
  2
  ACL2 !>(fact t)
  1> (ACL2_*1*_ACL2::FACT T)

  ACL2 Error in TOP-LEVEL:  The guard for the function symbol FACT, which
  is (INTEGERP X), is violated by the arguments in the call (FACT T).
  See :DOC trace for a useful debugging utility.  See :DOC set-guard-
  checking for information about suppressing this check with (set-guard-
  checking :none), as recommended for new users.

  ACL2 !>:set-guard-checking :all

  Leaving guard checking on, but changing value to :ALL.

  ACL2 !>(fact 2)
  1> (ACL2_*1*_ACL2::FACT 2)
    2> (FACT 2)
      3> (FACT 1)
        4> (FACT 0)
        <4 (FACT 1)
      <3 (FACT 1)
    <2 (FACT 2)
  <1 (ACL2_*1*_ACL2::FACT 2)
  2
  ACL2 !>(fact t)
  1> (ACL2_*1*_ACL2::FACT T)

  ACL2 Error in TOP-LEVEL:  The guard for the function symbol FACT, which
  is (INTEGERP X), is violated by the arguments in the call (FACT T).
  See :DOC trace for a useful debugging utility.  See :DOC set-guard-
  checking for information about suppressing this check with (set-guard-
  checking :none), as recommended for new users.

  ACL2 !>:set-guard-checking :none

  Turning off guard checking entirely.  To allow execution in raw Lisp
  for functions with guards other than T, while continuing to mask guard
  violations, :SET-GUARD-CHECKING NIL.  See :DOC set-guard-checking.

  ACL2 >(fact 2)
  1> (ACL2_*1*_ACL2::FACT 2)
    2> (ACL2_*1*_ACL2::FACT 1)
      3> (ACL2_*1*_ACL2::FACT 0)
      <3 (ACL2_*1*_ACL2::FACT 1)
    <2 (ACL2_*1*_ACL2::FACT 1)
  <1 (ACL2_*1*_ACL2::FACT 2)
  2
  ACL2 >(fact t)
  1> (ACL2_*1*_ACL2::FACT T)
  <1 (ACL2_*1*_ACL2::FACT 1)
  1
  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 >(fact 2)
  1> (ACL2_*1*_ACL2::FACT 2)
    2> (FACT 2)
      3> (FACT 1)
        4> (FACT 0)
        <4 (FACT 1)
      <3 (FACT 1)
    <2 (FACT 2)
  <1 (ACL2_*1*_ACL2::FACT 2)
  2
  ACL2 >(fact t)
  1> (ACL2_*1*_ACL2::FACT T)
  <1 (ACL2_*1*_ACL2::FACT 1)
  1
  ACL2 >:u
   L        1:x(DEFUN FACT (X) ...)
  ACL2 >:u
            0:x(EXIT-BOOT-STRAP-MODE)
  ACL2 >(defun fact (x)
           (declare (xargs :guard (integerp x)
                           :mode :logic))
           (if (posp x)
               (* x (fact (1- x)))
             1))

  For the admission of FACT we will use the relation O< (which is known
  to be well-founded on the domain recognized by O-P) and the measure
  (ACL2-COUNT X).  The non-trivial part of the measure conjecture is

  [[output omitted here]]

  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
   FACT
  ACL2 >(trace$ fact)
   ((FACT))
  ACL2 >:set-guard-checking t

  Turning guard checking on, value T.

  ACL2 !>(fact 2)
  1> (ACL2_*1*_ACL2::FACT 2)
    2> (FACT 2)
      3> (FACT 1)
        4> (FACT 0)
        <4 (FACT 1)
      <3 (FACT 1)
    <2 (FACT 2)
  <1 (ACL2_*1*_ACL2::FACT 2)
  2
  ACL2 !>(fact t)
  1> (ACL2_*1*_ACL2::FACT T)

  ACL2 Error in TOP-LEVEL:  The guard for the function symbol FACT, which
  is (INTEGERP X), is violated by the arguments in the call (FACT T).
  See :DOC trace for a useful debugging utility.  See :DOC set-guard-
  checking for information about suppressing this check with (set-guard-
  checking :none), as recommended for new users.

  ACL2 !>:set-guard-checking :all

  Leaving guard checking on, but changing value to :ALL.

  ACL2 !>(fact 2)
  1> (ACL2_*1*_ACL2::FACT 2)
    2> (FACT 2)
      3> (FACT 1)
        4> (FACT 0)
        <4 (FACT 1)
      <3 (FACT 1)
    <2 (FACT 2)
  <1 (ACL2_*1*_ACL2::FACT 2)
  2
  ACL2 !>(fact t)
  1> (ACL2_*1*_ACL2::FACT T)

  ACL2 Error in TOP-LEVEL:  The guard for the function symbol FACT, which
  is (INTEGERP X), is violated by the arguments in the call (FACT T).
  See :DOC trace for a useful debugging utility.  See :DOC set-guard-
  checking for information about suppressing this check with (set-guard-
  checking :none), as recommended for new users.

  ACL2 !>:set-guard-checking :none

  Turning off guard checking entirely.  To allow execution in raw Lisp
  for functions with guards other than T, while continuing to mask guard
  violations, :SET-GUARD-CHECKING NIL.  See :DOC set-guard-checking.

  ACL2 >(fact 2)
  1> (ACL2_*1*_ACL2::FACT 2)
    2> (ACL2_*1*_ACL2::FACT 1)
      3> (ACL2_*1*_ACL2::FACT 0)
      <3 (ACL2_*1*_ACL2::FACT 1)
    <2 (ACL2_*1*_ACL2::FACT 1)
  <1 (ACL2_*1*_ACL2::FACT 2)
  2
  ACL2 >(fact t)
  1> (ACL2_*1*_ACL2::FACT T)
  <1 (ACL2_*1*_ACL2::FACT 1)
  1
  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 >(fact 2)
  1> (ACL2_*1*_ACL2::FACT 2)
    2> (FACT 2)
      3> (FACT 1)
        4> (FACT 0)
        <4 (FACT 1)
      <3 (FACT 1)
    <2 (FACT 2)
  <1 (ACL2_*1*_ACL2::FACT 2)
  2
  ACL2 >(fact t)
  1> (ACL2_*1*_ACL2::FACT T)
  <1 (ACL2_*1*_ACL2::FACT 1)
  1
  ACL2 >:u
            0:x(EXIT-BOOT-STRAP-MODE)
  ACL2 >(defun fact (x)
           (declare (xargs :guard t
                           :verify-guards nil
                           :mode :logic))
           (if (posp x)
               (* x (fact (1- x)))
             1))

  For the admission of FACT we will use the relation O< (which is known
  to be well-founded on the domain recognized by O-P) and the measure
  (ACL2-COUNT X).  The non-trivial part of the measure conjecture is

  [[output omitted here]]

  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
   FACT
  ACL2 >(trace$ fact)
   ((FACT))
  ACL2 >:set-guard-checking t

  Turning guard checking on, value T.

  ACL2 !>(fact 2)
  1> (ACL2_*1*_ACL2::FACT 2)
    2> (ACL2_*1*_ACL2::FACT 1)
      3> (ACL2_*1*_ACL2::FACT 0)
      <3 (ACL2_*1*_ACL2::FACT 1)
    <2 (ACL2_*1*_ACL2::FACT 1)
  <1 (ACL2_*1*_ACL2::FACT 2)
  2
  ACL2 !>(fact t)
  1> (ACL2_*1*_ACL2::FACT T)
  <1 (ACL2_*1*_ACL2::FACT 1)
  1
  ACL2 !>:set-guard-checking :all

  Leaving guard checking on, but changing value to :ALL.

  ACL2 !>(fact 2)
  1> (ACL2_*1*_ACL2::FACT 2)
    2> (ACL2_*1*_ACL2::FACT 1)
      3> (ACL2_*1*_ACL2::FACT 0)
      <3 (ACL2_*1*_ACL2::FACT 1)
    <2 (ACL2_*1*_ACL2::FACT 1)
  <1 (ACL2_*1*_ACL2::FACT 2)
  2
  ACL2 !>(fact t)
  1> (ACL2_*1*_ACL2::FACT T)
  <1 (ACL2_*1*_ACL2::FACT 1)
  1
  ACL2 !>:set-guard-checking :none

  Turning off guard checking entirely.  To allow execution in raw Lisp
  for functions with guards other than T, while continuing to mask guard
  violations, :SET-GUARD-CHECKING NIL.  See :DOC set-guard-checking.

  ACL2 >(fact 2)
  1> (ACL2_*1*_ACL2::FACT 2)
    2> (ACL2_*1*_ACL2::FACT 1)
      3> (ACL2_*1*_ACL2::FACT 0)
      <3 (ACL2_*1*_ACL2::FACT 1)
    <2 (ACL2_*1*_ACL2::FACT 1)
  <1 (ACL2_*1*_ACL2::FACT 2)
  2
  ACL2 >(fact t)
  1> (ACL2_*1*_ACL2::FACT T)
  <1 (ACL2_*1*_ACL2::FACT 1)
  1
  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 >(fact 2)
  1> (ACL2_*1*_ACL2::FACT 2)
    2> (ACL2_*1*_ACL2::FACT 1)
      3> (ACL2_*1*_ACL2::FACT 0)
      <3 (ACL2_*1*_ACL2::FACT 1)
    <2 (ACL2_*1*_ACL2::FACT 1)
  <1 (ACL2_*1*_ACL2::FACT 2)
  2
  ACL2 >(fact t)
  1> (ACL2_*1*_ACL2::FACT T)
  <1 (ACL2_*1*_ACL2::FACT 1)
  1
  ACL2 >(verify-guards fact)

  Computing the guard conjecture for FACT....

  The guard conjecture for FACT is trivial to prove, given the :compound-
  recognizer rule POSP-COMPOUND-RECOGNIZER and the :type-prescription
  rule FACT.  FACT is compliant with Common Lisp.

  Summary
  Form:  ( VERIFY-GUARDS FACT)
  Rules: ((:COMPOUND-RECOGNIZER POSP-COMPOUND-RECOGNIZER)
          (:TYPE-PRESCRIPTION FACT))
  Warnings:  None
  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
   FACT

  [[Note added to log: No need to trace fact again after verify-guards.]]

  ACL2 >:set-guard-checking t

  Turning guard checking on, value T.

  ACL2 !>(fact 2)
  1> (ACL2_*1*_ACL2::FACT 2)
    2> (FACT 2)
      3> (FACT 1)
        4> (FACT 0)
        <4 (FACT 1)
      <3 (FACT 1)
    <2 (FACT 2)
  <1 (ACL2_*1*_ACL2::FACT 2)
  2
  ACL2 !>(fact t)
  1> (ACL2_*1*_ACL2::FACT T)
    2> (FACT T)
    <2 (FACT 1)
  <1 (ACL2_*1*_ACL2::FACT 1)
  1
  ACL2 !>:set-guard-checking :all

  Leaving guard checking on, but changing value to :ALL.

  ACL2 !>(fact 2)
  1> (ACL2_*1*_ACL2::FACT 2)
    2> (FACT 2)
      3> (FACT 1)
        4> (FACT 0)
        <4 (FACT 1)
      <3 (FACT 1)
    <2 (FACT 2)
  <1 (ACL2_*1*_ACL2::FACT 2)
  2
  ACL2 !>(fact t)
  1> (ACL2_*1*_ACL2::FACT T)
    2> (FACT T)
    <2 (FACT 1)
  <1 (ACL2_*1*_ACL2::FACT 1)
  1
  ACL2 !>:set-guard-checking :none

  Turning off guard checking entirely.  To allow execution in raw Lisp
  for functions with guards other than T, while continuing to mask guard
  violations, :SET-GUARD-CHECKING NIL.  See :DOC set-guard-checking.

  ACL2 >(fact 2)
  1> (ACL2_*1*_ACL2::FACT 2)
    2> (FACT 2)
      3> (FACT 1)
        4> (FACT 0)
        <4 (FACT 1)
      <3 (FACT 1)
    <2 (FACT 2)
  <1 (ACL2_*1*_ACL2::FACT 2)
  2
  ACL2 >(fact t)
  1> (ACL2_*1*_ACL2::FACT T)
    2> (FACT T)
    <2 (FACT 1)
  <1 (ACL2_*1*_ACL2::FACT 1)
  1
  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 >(fact 2)
  1> (ACL2_*1*_ACL2::FACT 2)
    2> (FACT 2)
      3> (FACT 1)
        4> (FACT 0)
        <4 (FACT 1)
      <3 (FACT 1)
    <2 (FACT 2)
  <1 (ACL2_*1*_ACL2::FACT 2)
  2
  ACL2 >(fact t)
  1> (ACL2_*1*_ACL2::FACT T)
    2> (FACT T)
    <2 (FACT 1)
  <1 (ACL2_*1*_ACL2::FACT 1)
  1
  ACL2 >
 })")

(defxdoc guard-evaluation-examples-script
  :parents (guard)
  :short "A script to show combinations of @(see defun-mode)s and @(see guard)-checking"
  :long "<p>Below is a script that illustrates the combination of @(see
 defun-mode)s &mdash; @(':')@(tsee program) mode, @(':')@(tsee logic) mode
 without @(see guard)s verified, and @(':')@(tsee logic) mode with @(see
 guard)s verified &mdash; with values from @(tsee set-guard-checking) &mdash;
 @('t') (the default), @(':all'), @(':none'), and @('nil').  (It does not
 illustrate the value @(':nowarn'), which is the same as @('t') except for
 inhibiting a warning.)  The script also illustrates cases where the guard is
 not, or is, @('t').</p>

 <p>See @(see guard-evaluation-examples-log) for result of running this script.
 Before presenting the script below, we give some instructions in case you want
 to run it yourself.</p>

 <p>See @(see set-guard-checking) for discussion of the interaction between
 @(see defun-mode)s and @(see guard)-checking that is illustrated by this
 script.  Also see @(see guard-evaluation-table) for a succinct table, with
 associated discussion, that covers in detail the interactions illustrated
 here.</p>

 <p>The script mentions the running of ``Tracing Code''.  The code is the
 following sequence of commands.</p>

 @({
  (trace$ fact)
  :set-guard-checking t
  (fact 2)
  (fact t)
  :set-guard-checking :all
  (fact 2)
  (fact t)
  :set-guard-checking :none
  (fact 2)
  (fact t)
  :set-guard-checking nil
  (fact 2)
  (fact t)
 })

 <p>If you want to run the script yourself, you may find it handy to use the
 following Emacs keyboard macro for running the tracing code in 2-window mode,
 with the cursor in the window with the script and ACL2 running in the other
 window.  The @('define-key') command is optional, in case you want to put that
 keyboard macro on a key &mdash; though in that case you'll need to have
 defined @('ctl-t-keymap'), which happens automatically if you load file
 @('emacs-acl2.el'); see :DOC emacs.</p>

 @({
  (fset 'step-guard-script
     [?C-a ?C-  ?C-e ?M-w ?C-a ?C-n
      ?C-x ?o ?M-> ?C-y return ?C-x ?o])

  (define-key ctl-t-keymap "r" 'step-guard-script)
 })

 <p>The script follows.</p>

 @({
  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  ;;; Program mode
  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

  (defun fact (x)
           (declare (xargs :guard (integerp x)
                           :mode :program))
           (if (posp x)
               (* x (fact (1- x)))
             1))

  ; Run the Tracing Code here.  It shows execution in raw Lisp in the t and nil
  ; cases of :set-guard-checking, but not in the :all or :none cases.  We get a
  ; guard violation for argument t in the case :set-guard-checking t.

  :u

  (defun fact (x)
           (declare (xargs :guard t
                           :mode :program))
           (if (posp x)
               (* x (fact (1- x)))
             1))

  ; Run the Tracing Code here.  It should give the same results as above,
  ; except that we no longer get a guard violation in the case
  ; :set-guard-checking t.

  :u

  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  ;;; Logic mode, guard other than t
  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

  (defun fact (x)
           (declare (xargs :guard (integerp x)
                           :verify-guards nil
                           :mode :logic))
           (if (posp x)
               (* x (fact (1- x)))
             1))

  ; Run the Tracing Code here.  It should give guard violations for (fact t)
  ; with guard-checking set to t or :all.  It should never run in raw Lisp,
  ; because we have not verified guards.  In the t case, we can get a warning
  ; about avoiding the guard check on recursive calls, but only if we do not
  ; trace the function, fact.

  (verify-guards fact)

  ; Run the Tracing Code here.  The results should be as described just above,
  ; except that now we go into raw Lisp for (fact 2) with guard-checking other
  ; than :none.

  :u
  :u

  ; The following definition is the same as above, except that guards are
  ; verified.

  (defun fact (x)
           (declare (xargs :guard (integerp x)
                           :mode :logic))
           (if (posp x)
               (* x (fact (1- x)))
             1))

  ; Run the Tracing Code here.  We should get the same traces as in the
  ; immediately preceding case, since guards had been verified in both cases.

  :u

  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  ;;; Logic mode, guard t
  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

  (defun fact (x)
           (declare (xargs :guard t
                           :verify-guards nil
                           :mode :logic))
           (if (posp x)
               (* x (fact (1- x)))
             1))

  ; Run the Tracing Code here.  We should never go in to raw Lisp, because
  ; guards have not been verified.  We will see the same traces for (fact 2) as
  ; with the (integerp x) guard above with :verify-guards nil specified, except
  ; that even without tracing, there is no warning for :set-guard-checking t
  ; about recursive calls.  And, there are no guard violations for (fact t), of
  ; course, since posp (necessarily, if we are to verify guards) has a guard of
  ; t.

  (verify-guards fact)

  ; Run the Tracing Code here.  You shouldn't see any surprises.  Note however
  ; that if we back up to the start (using :u :u) and then define fact as just
  ; above but without :verify-guards nil, then the :none setting will allow us
  ; to go into raw Lisp: although :none generally avoids execution of raw Lisp
  ; counterparts, it allows this when the guard is T and guards have been
  ; verified.
 })")

(defxdoc guard-evaluation-table
  :parents (guard)
  :short "A table that shows combinations of @(see defun-mode)s and @(see guard)-checking"
  :long "<p>See @(see set-guard-checking) for an introduction to the topic
 discussed here.  Also see @(see guard) for a general discussion of guards, and
 see @(see guard-evaluation-examples-script) for a script that illustrates
 combinations presented below.</p>

 <p>Note: The default setting for guard-checking (that is, the initial value
 for @(see state) global @('(@ guard-checking-on)')) is @('T').</p>

 <p>The table below illustrates the interaction of the @(see defun-mode) with
 the value supplied to @(tsee set-guard-checking).  The first row considers
 functions defined in @(':')@(tsee program) mode; the other two consider
 functions defined in @(':')@(tsee logic) mode.  The columns correspond to four
 values of state global @(''guard-checking-on'), as supplied to @(tsee
 set-guard-checking).  (A fifth value, @(':nowarn'), is similar to @('t') but
 suppresses warnings; a remark with details for system hackers is at the end of
 this topic.)  Note that @(''guard-checking-on') is set to @('nil') during
 proofs but is set to @('t') during @(tsee certify-book), and @(tsee
 include-book), regardless of how this variable has been set in the top-level
 loop (see the ``Essay on Guard Checking'' in source file
 @('other-events.lisp') if you are interested in a rationale).</p>

 <p>Below this table, we make some comments about its entries, ordered by row
 and then by column.  For example, when we refer to ``b2'' we are discussing
 the execution of a @(':')@(tsee logic) mode function whose guards have not
 been verified, after having executed @(':')@(tsee set-guard-checking)@('
 :all').</p>

 @({
     guard-checking-on:  (1)t      (2):all   (3):none   (4)nil

   (a) :program             a1        a2        a3        a4
   (b) guards not verified  b1        b2        b3        b4
   (c) guards verified      c1        c2        c3        c4
 })

 <p>a1. Check the @(see guard) upon entry, then use the raw Lisp code if the
 guard checks (else cause an error).  This is a common setting when one wants a
 little guard checking but also wants the efficiency of raw Lisp.  But note
 that you can get raw Lisp errors.  For example, if you make the definition
 @('(defun foo (x) (car x))') in @(':')@(tsee program) mode and execute
 @(':')@(tsee set-guard-checking)@(' t'), and then execute @('(foo 3)'), you
 will likely get an error from the call @('(car 3)') made in raw Lisp.</p>

 <p>a2. For built-in (predefined) functions, see a1 instead.
 Otherwise:<br></br>

 Check the @(see guard), without exception.  Thus, we never run the raw Lisp
 code in this case.  This can be useful when testing @(':')@(tsee program) mode
 functions, but you may want to run @(':')@(tsee comp)@(' t') or at least
 @(':')@(tsee comp)@(' :exec') in this case, so that the execution is done
 using compiled code.</p>

 <p>a3. For built-in (predefined) functions, see a4 instead.
 Otherwise:<br></br>

 Do not check the @(see guard).  For @(':')@(tsee program) mode functions, we
 never run the raw Lisp code in this case; so if you care about efficiency, see
 the comment in a2 above about @(':')@(tsee comp).  This combination is useful
 if you are using ACL2 as a programming language and do not want to prove
 theorems about your functions or suffer @(see guard) violations.  In this
 case, you can forget about any connection between ACL2 and Common Lisp.</p>

 <p>a4. Run the raw Lisp code without checking @(see guard)s at all.  Thus, for
 @(':')@(tsee program) mode functions, the @('nil') setting is often preferable
 to the @(':none') setting because you get the efficiency of raw Lisp
 execution.  However, with @('nil') you can therefore get hard Lisp errors as
 in a1 above.</p>

 <p>b1. Guards are checked at the top-level, though not at self-recursive
 calls.  We never run the raw Lisp code in this case; guards would need to be
 verified first.</p>

 <p>b2. Unlike the @('t') setting, guards are checked even on self-recursive
 calls.  But like the @('t') setting, we do not run the raw Lisp code.  Use
 this setting if you want guards checked on each recursive call in spite of the
 cost of doing so.</p>

 <p>b3, b4. Execution avoids the raw Lisp code and never checks guards.  The
 @('nil') and @(':none') settings behave the same in this case (i.e., for
 @(':')@(tsee logic) mode functions whose guards have not been verified),
 except that recursive calls are never inlined for @(':none') and tracing (see
 @(see trace)) will show recursive calls for @(':none') but not for
 @('nil').</p>

 <p>c1, c2. Guards are checked.  If the checks pass, evaluation takes place
 using the raw Lisp code.  If the checks fail, we get a guard violation.
 Either way, we do not execute ``in the logic''; we only execute using the raw
 Lisp code.  Note that @('t') and @(':all') behave the same in this case,
 (i.e. for @(':')@(tsee logic) mode functions whose @(see guard)s have been
 verified).</p>

 <p>c3, c4. For the @(':none') and @('nil') settings, @(':')@(tsee logic) mode
 functions whose guards have been verified will never cause guard violations.
 However, with @('nil') and for built-in functions in @(':logic') mode, guards
 are still checked: if the check succeeds, then evaluation is done using the
 raw Lisp code, and if not, it is done by the ``logic'' code, including
 self-recursive calls (though unlike the @('t') case, we will not see a warning
 about this).  But with @(':none') for user-defined functions, no guard
 checking is done, and the only time the raw Lisp code will be executed is when
 the guard is @('t') and guards are verified at the time the
 executable-counterpart of the function is defined (i.e., when the function is
 admitted unless it is later defined again and compiled using @(':')@(tsee
 comp)).  Thus, if you use @(':none') and you want a function @('(foo x)') with
 guard @('(g x)') to execute using raw Lisp code, you can write a
 ``wrapper''function with a guard of @('t'):</p>

 @({
  (defun foo-wrap (x)
    (declare (xargs :guard t))
    (if (g x)
        (foo x)
      'do-not-case))
 })

 <p>If you want the speed of executing raw Lisp code and you have non-trivial
 guards on functions that you want to call at the top-level, use @('nil')
 rather than @(':none').</p>

 <p>Remark for system hackers.  As noted above, a fifth value, @(':nowarn'), is
 similar to @('t') but suppresses warnings.  Only the four values in the column
 headers above and @(':nowarn') are legal for @(tsee set-guard-checking),
 @(tsee with-guard-checking), @(tsee with-guard-checking-error-triple), and
 @(tsee with-guard-checking-event).  Behavior is technically undefined if you
 set @(see state) global @('guard-checking-on') directly to other than those
 five values, say using @(tsee assign), @(tsee f-put-global), or @(tsee
 state-global-let*).  However, as of this writing (in August 2021), such a
 value will cause the same behavior as value @(':nowarn').  End of
 Remark.</p>")

(defxdoc guard-example
  :parents (tutorial5-miscellaneous-examples guard)
  :short "A brief transcript illustrating @(see guard)s in ACL2"
  :long "<p>This note addresses the question: what is the use of @(see guard)s
 in ACL2?  Although we recommend that beginners try to avoid @(see guard)s for
 a while, we hope that the summary here is reasonably self-contained and will
 provide a helpful introduction to guards in ACL2.  For a more systematic
 discussion, see @(see guard).  For a summary of that topic, see @(see
 guard-quick-reference).</p>

 <p>Before we get into the issue of @(see guard)s, let us note that there are
 two important &ldquo;modes&rdquo;:</p>

 <blockquote>

 <p>@(see defun-mode) &mdash; &ldquo;Does this @(see defun) add an
 axiom (&lsquo;logic mode&rsquo;) or not (`:program mode')?&rdquo; (See @(see
 defun-mode).)  Only @(see logic) mode functions can have their &ldquo;@(see
 guard)s verified&rdquo; via mechanized proof; see @(see verify-guards).</p>

 <p>@(tsee set-guard-checking) &mdash; &ldquo;Should runtime @(see guard)
 violations signal an error (@(':all'), and usually with @('t') or
 @(':nowarn')) or go undetected (@('nil'), @(':none'))?  The question relates
 to the use of Common Lisp to evaluate expressions; see @(see
 set-guard-checking).</p>

 </blockquote>

 <h3>Examples of prompts</h3>

 <p>Here are some examples of the relation between the ACL2 @(see prompt) and
 the &ldquo;modes&rdquo; discussed above.  Also see @(see
 default-print-prompt).  The first examples all have @(tsee ld-skip-proofsp)
 equal to @('nil'); that is, proofs are <i>not</i> skipped.</p>

 @({
    ACL2 !>    ; logic mode with guard checking on
    ACL2 >     ; logic mode with guard checking off
    ACL2 p!>   ; program mode with guard checking on
    ACL2 p>    ; program mode with guard checking off
 })

 <p>Here are some examples with @(tsee default-defun-mode) equal to
 @(':logic').</p>

 @({
    ACL2 >     ; guard checking off, ld-skip-proofsp nil
    ACL2 s>    ; guard checking off, ld-skip-proofsp t
    ACL2 !>    ; guard checking on, ld-skip-proofsp nil
    ACL2 !s>   ; guard checking on, ld-skip-proofsp t
 })

 <h3>Sample session</h3>

 @({
  ACL2 !>(+ 'abc 3)


  ACL2 Error [Evaluation] in TOP-LEVEL:  The guard for the function call
  (BINARY-+ X Y), which is (AND (ACL2-NUMBERP X) (ACL2-NUMBERP Y)), is
  violated by the arguments in the call (BINARY-+ 'ABC 3).
  See :DOC set-guard-checking for information about suppressing this
  check with (set-guard-checking :none), as recommended for new users.
  To debug see :DOC print-gv, see :DOC trace, and see :DOC wet.

  ACL2 !>:set-guard-checking nil
  [[.. output elided ..]]
  ACL2 >(+ 'abc 3)
  3
  ACL2 >(< 'abc 3)
  T
  ACL2 >(< 3 'abc)
  NIL
  ACL2 >(< -3 'abc)
  T
  ACL2 >:set-guard-checking t

  Turning guard checking on, value T.

  ACL2 !>(defun sum-list (x)
          (declare (xargs :guard (integer-listp x)
                          :verify-guards nil))
          (cond ((endp x) 0)
                (t (+ (car x) (sum-list (cdr x))))))

  The admission of SUM-LIST 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 observe that the type of SUM-LIST is described by the
  theorem (ACL2-NUMBERP (SUM-LIST X)).  We used primitive type
  reasoning.

  Summary
  Form:  ( DEFUN SUM-LIST ...)
  Rules: ((:FAKE-RUNE-FOR-TYPE-SET NIL))
  Time:  0.01 seconds (prove: 0.00, print: 0.00, other: 0.03)
   SUM-LIST
  ACL2 !>(sum-list '(1 2 3))

  ACL2 Warning [Guards] in TOP-LEVEL:  Guard-checking will be inhibited
  for some recursive calls, including SUM-LIST; see :DOC guard-checking-
  inhibited.

  6
  ACL2 !>(sum-list '(1 2 abc 3))


  ACL2 Error [Evaluation] in TOP-LEVEL:  The guard for the function call
  (SUM-LIST X), which is (INTEGER-LISTP X), is violated by the arguments
  in the call (SUM-LIST '(1 2 ABC 3)).
  See :DOC set-guard-checking for information about suppressing this
  check with (set-guard-checking :none), as recommended for new users.
  To debug see :DOC print-gv, see :DOC trace, and see :DOC wet.

  ACL2 !>:set-guard-checking nil
  [[.. output elided ..]]
  ACL2 >(sum-list '(1 2 abc 3))
  6
  ACL2 >(defthm sum-list-append
         (equal (sum-list (append a b))
                (+ (sum-list a) (sum-list b))))

  *1 (the initial Goal, a key checkpoint) is pushed for proof by induction.

  Perhaps we can prove *1 by induction.  Three induction schemes are
  suggested by this conjecture.  Subsumption reduces that number to two.
  However, one of these is flawed and so we are left with one viable
  candidate.

  [[.. output elided ..]]

  *1 is COMPLETED!
  Thus key checkpoint Goal is COMPLETED!

  Q.E.D.

  Summary
  Form:  ( DEFTHM SUM-LIST-APPEND ...)
  Rules: ((:DEFINITION BINARY-APPEND)
          (:DEFINITION ENDP)
  [[.. output elided ..]]
          (:TYPE-PRESCRIPTION SUM-LIST))

  Time:  0.01 seconds (prove: 0.01, print: 0.00, other: 0.00)
  Prover steps counted:  470
   SUM-LIST-APPEND
 })

 <h3>Guard verification for functions</h3>

 <p>See @(see declare), and @(see xargs), and @(see verify-guards) for related
 background, though we intend what follows to be self-explanatory.</p>

 @({
        Declare Form                        Guards Verified?

    (declare (xargs :mode :program ...))          no
    (declare (xargs :guard g))                    yes
    (declare (xargs :guard g :verify-guards nil)) no
    (declare (xargs ...<no :guard>...))           no

  ACL2 >:pe sum-list
   L         1  (DEFUN SUM-LIST (X)
                  (DECLARE (XARGS :GUARD (INTEGER-LISTP X)
                                  :VERIFY-GUARDS NIL))
                  (COND ((ENDP X) 0)
                        (T (+ (CAR X) (SUM-LIST (CDR X))))))
  ACL2 >(verify-guards sum-list)

  Computing the guard conjecture for SUM-LIST....

  The non-trivial part of the guard conjecture for SUM-LIST, given the

  [[.. output elided ..]]

  Q.E.D.

  That completes the proof of the guard theorem for SUM-LIST.  SUM-LIST
  is compliant with Common Lisp.

  Summary
  Form:  ( VERIFY-GUARDS SUM-LIST)
  Rules: ((:DEFINITION ENDP)
  [[.. output elided ..]]
          (:TYPE-PRESCRIPTION SUM-LIST))
  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
  Prover steps counted:  115
   SUM-LIST
  ACL2 >:pe sum-list
   LV        1  (DEFUN SUM-LIST (X)
                  (DECLARE (XARGS :GUARD (INTEGER-LISTP X)
                                  :VERIFY-GUARDS NIL))
                  (COND ((ENDP X) 0)
                        (T (+ (CAR X) (SUM-LIST (CDR X))))))
  ACL2 >:set-guard-checking t

  Turning guard checking on, value T.

  ACL2 !>(sum-list '(1 2 abc 3))


  ACL2 Error [Evaluation] in TOP-LEVEL:  The guard for the function call
  (SUM-LIST X), which is (INTEGER-LISTP X), is violated by the arguments
  in the call (SUM-LIST '(1 2 ABC 3)).
  See :DOC set-guard-checking for information about suppressing this
  check with (set-guard-checking :none), as recommended for new users.
  To debug see :DOC print-gv, see :DOC trace, and see :DOC wet.

  ACL2 !>:set-guard-checking nil
  [[.. output elided ..]]
  ACL2 >(sum-list '(1 2 abc 3))
  6
  ACL2 >
  })

  <p>We continue this demo by tracing @('sum-list').  (See @(see trace$).)  The
  calls shown below of @('ACL2_*1*_ACL2::SUM-LIST') are calls of the logical
  version, or <i>executable-counterpart</i>, of @('sum-list'); also see @(see
  evaluation).  Note that the guard-checking value is still @('nil').  So the
  logical version of @('sum-list') calls the Common Lisp @('sum-list') function
  when the @(see guard) of &ldquo;list of integers&rdquo; is true of its input,
  i.e., its input satisfies @(tsee integer-listp); but otherwise, evaluation
  continues using its executable-counterpart.</p>

  @({
  ACL2 >(trace$ sum-list)
   ((SUM-LIST))
  ACL2 >(sum-list '(1 2 abc 3))
  1> (ACL2_*1*_ACL2::SUM-LIST (1 2 ABC 3))
    2> (ACL2_*1*_ACL2::SUM-LIST (2 ABC 3))
      3> (ACL2_*1*_ACL2::SUM-LIST (ABC 3))
        4> (ACL2_*1*_ACL2::SUM-LIST (3))
          5> (SUM-LIST (3))
            6> (SUM-LIST NIL)
            <6 (SUM-LIST 0)
          <5 (SUM-LIST 3)
        <4 (ACL2_*1*_ACL2::SUM-LIST 3)
      <3 (ACL2_*1*_ACL2::SUM-LIST 3)
    <2 (ACL2_*1*_ACL2::SUM-LIST 5)
  <1 (ACL2_*1*_ACL2::SUM-LIST 6)
  6
  ACL2 >
  })

  <h3>Guard verification for theorems</h3>

  <p>For a theorem to be guard-verified, its statement should be executable
  without error in Common Lisp.  The following is thus not guard-verifiable,
  since its evaluation can cause an error if @('A') and @('B') are not both
  lists of numbers.</p>

  @({
  ACL2 >:pe sum-list-append
             2  (DEFTHM SUM-LIST-APPEND
                  (EQUAL (SUM-LIST (APPEND A B))
                         (+ (SUM-LIST A) (SUM-LIST B))))
  ACL2 >(verify-guards sum-list-append)

  Computing the guard conjecture for SUM-LIST-APPEND....

  The non-trivial part of the guard conjecture for
  SUM-LIST-APPEND, given the :type-prescription rule SUM-LIST,
  is

  Goal
  (AND (TRUE-LISTP A)
       (INTEGER-LISTP A)
       (INTEGER-LISTP (APPEND A B))
       (INTEGER-LISTP B)).

  ******** FAILED ********
  ACL2 >
  })

  <p>Perhaps surprisingly, a @(tsee defthm) event with statement</p>

  @({
  (implies (and (integer-listp a)
                (integer-listp b))
           (equal (sum-list (append a b))
                  (+ (sum-list a) (sum-list b))))
  })

  <p>is still not guard-verifiable.  The reason is that @(tsee implies) is a
  function, so its arguments are both always evaluated &mdash; in particular,
  its second argument is evaluated even if its first argument evaluates to
  @('nil').  Here is a way to fix that problem.</p>

  @({
  ACL2 >(defthm common-lisp-sum-list-append
           (if (and (integer-listp a)
                    (integer-listp b))
               (equal (sum-list (append a b))
                      (+ (sum-list a) (sum-list b)))
               t)
           :rule-classes nil)

  Q.E.D.

  Summary
  Form:  ( DEFTHM COMMON-LISP-SUM-LIST-APPEND ...)
  Rules: ((:REWRITE SUM-LIST-APPEND))
  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
  Prover steps counted:  23
   COMMON-LISP-SUM-LIST-APPEND
  ACL2 >(verify-guards common-lisp-sum-list-append)

  Computing the guard conjecture for COMMON-LISP-SUM-LIST-APPEND....

  The non-trivial part of the guard conjecture for COMMON-LISP-SUM-LIST-APPEND,
  given the :forward-chaining rules ACL2-NUMBER-LISTP-FORWARD-TO-TRUE-LISTP,
  INTEGER-LISTP-FORWARD-TO-RATIONAL-LISTP and
  RATIONAL-LISTP-FORWARD-TO-ACL2-NUMBER-LISTP and the :type-prescription
  rules ACL2-NUMBER-LISTP, INTEGER-LISTP, RATIONAL-LISTP and SUM-LIST,
  is

  Goal
  (IMPLIES (AND (INTEGER-LISTP A)
                (INTEGER-LISTP B))
           (INTEGER-LISTP (APPEND A B))).

  [[.. output elided ..]]

  Q.E.D.

  That completes the proof of the guard theorem for
  COMMON-LISP-SUM-LIST-APPEND.  COMMON-LISP-SUM-LIST-APPEND is compliant
  with Common Lisp.

  Summary
  Form:  ( VERIFY-GUARDS COMMON-LISP-SUM-LIST-APPEND)
  Rules: ((:DEFINITION BINARY-APPEND)
  [[.. output elided ..]]
          (:TYPE-PRESCRIPTION SUM-LIST))
  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
  Prover steps counted:  565
   COMMON-LISP-SUM-LIST-APPEND
  ACL2 >
 })

 <p>Guard verification fails when the theorem is for &ldquo;code&rdquo; that
 cannot even be parsed (or &ldquo;translated&rdquo;; see @(see term)) as
 executable code.</p>

 @({
  ACL2 >(defthm foo (consp (mv x y)))

  Q.E.D.

  The storage of FOO depends upon primitive type reasoning.

  Summary
  Form:  ( DEFTHM FOO ...)
  Rules: ((:FAKE-RUNE-FOR-TYPE-SET NIL))
  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
   FOO
  ACL2 >(verify-guards foo)


  ACL2 Error in ( VERIFY-GUARDS FOO):  The guards for FOO cannot be verified
  because its formula has the wrong syntactic form for evaluation, perhaps
  due to multiple-value or stobj restrictions.  See :DOC verify-guards.


  Summary
  Form:  ( VERIFY-GUARDS FOO)
  Rules: NIL
  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)

  ACL2 Error [Failure] in ( VERIFY-GUARDS FOO):  See :DOC failure.

  ******** FAILED ********
  ACL2 >
 })")

(defxdoc guard-formula-utilities
  :parents (guard)
  :short "Utilities that show guard proof obligations"
  :long "<p>See @(see verify-guards) and see @(see guard) for discussions of
 guards.  Here we discuss several utilities that provide the proof obligations
 for guards, and briefly compare what is offered by each.  Of course, see the
 documentation of each utility for details.</p>

 <p>The first pair of utilities captures formulas produced during guard
 verification.</p>

 <blockquote>

 <p>@(tsee Verify-guards-formula): Use this to see what the corresponding
 @(tsee verify-guards) event prints, but without following through with a proof
 attempt.  This utility is only for output, without returning an interesting
 value.</p>

 <p>@(tsee Guard-obligation): This function is a programmatic version of the
 macro, @(tsee verify-guards-formula).  It provides the guard obligation as a
 set of @(see clause)s, along with other information.</p>

 </blockquote>

 <p>The second pair of utilities captures the formula provided when a
 @(':guard-theorem') is supplied for a @(':use') hint.</p>

 <blockquote>

 <p>@(tsee Gthm): This macro returns a user-level (``untranslated'')
 representation of the @(see term) that is generated for a @(':guard-theorem')
 @(see lemma-instance).  Options control whether or not simplification and
 @(see guard-debug) are used.</p>

 <p>@(tsee Guard-theorem): This utility is like @(see gthm), except that it is
 a function rather than a macro and it returns a translated term (a @(tsee
 termp)).</p>

 </blockquote>

 <p>We conclude by contrasting these two pairs of utilities.</p>

 <ul>

 <li>The first pair can take as input as either a function symbol or a term;
 for the second pair a function symbol (not a term) is required.</li>

 <li>The level of simplification differs between the two pairs.  See @(see
 guard-simplification) for a detailed explanation; here are highlights.  The
 first pair simplifies (by default) with respect to the @(see current-theory)
 before producing the guard proof obligation formula, as is typically done when
 verifying guards; but the second pair only performs the theory-independent
 simplification done for a @(':guard-theorem') specified in a @(':use') hint,
 or if a suitable option is supplied, no simplification at all.</li>

 <li>The two pairs differ in their output @(see signature)s: in particular, the
 utilities in the first pair return multiple values while those in the second
 pair return a single value.</li>

 </ul>")

(defxdoc guard-holders
  :parents (rule-classes term guard)
  :short "Remove trivial calls from a @(see term)"
  :long "<p>For many @(see rule-classes), the process of converting terms to
 rules includes the removal of certain trivial calls from the term.  Such
 removal is performed in some other settings as well, including @(see hints)
 processing, generating proof obligations for @(see guard)s and termination,
 and the storing of induction schemes and @(see constraint)s.</p>

 <p>In all such cases, the resulting term is provably equivalent to the input
 term.  A common example is to replace the term @('(prog2$ term1 term2)') by
 the term @('term2').  But @('(prog2$ term1 term2)') is really an abbreviation
 for (i.e., macroexpands to) the term @('(return-last 'progn term1 term2)'); so
 a more accurate explanation, at the level of proper ACL2 @(see term)s, is that
 the call of function @(tsee return-last) is replaced by its last argument.
 ACL2 identifies certain such transformations, from a term to a trivial
 simplification of it, such that the input and output are provably equal.  We
 historically have referred to the process of making such replacements as
 ``removing guard holders.''  (For a discussion of the connection to guards,
 see the ``Essay on the Removal of Guard Holders'' in the ACL2 sources.)</p>

 <p>The process of removing guard-holders includes the transformations below.
 That process is also applied to each argument of a function call and to the
 bodies of @(see lambda) expressions (see @(see term)), usually including
 quoted lambda expressions that appear in an argument position with @(see ilk)
 @(':FN') (see @(see apply$)).</p>

 @({
 (return-last term0 term1 term2)  ==>  term2

 (mv-list n term)                 ==>  term

 (cons-with-hint x y)             ==>  (cons x y)

 (the-check guard x y)            ==>  y

 (from-df x)                      ==>  x

 (to-df 'r)                       ==>  'r ; only when r satisfies dfp

 (df0)                            ==>  0

 (df1)                            ==>  1

 (do$ x1 x2 x3 x4 x5 'u1)         ==> (do$ x1 x2 x3 x4 x5 'nil)
                                      ; only when u1 is non-nil

 ; For replacing a term (the type term) by term:
 ((lambda (y) (the-check guard x y))
  val)                            ==>  val

 ; For replacing equality aliases; for example, this transforms
 ; the macroexpansion of (member x y) to (member-equal x y):
 (('LAMBDA (f1 ... fk) ('RETURN-LAST ''MBE1-RAW exec logic))
  a1 ... ak)                      ==>  logic

 ; For other than measure theorems and induction schemes, remove lambda
 ; applications that are ``trivial'' in either of the following two senses.

 ; For replacing a term (let ((v term)) v) by term:
 (('LAMBDA (v) v) term)           ==>  term

 ; When each formal is equal to the corresponding actual:
 (('LAMBDA (f1 ... fk) body)
  f1 ... fk)                      ==>  body
 })

 <p>Because of how @(tsee mbe) and @(tsee ec-call) are defined in terms of
 @(tsee return-last), the expressions @('(mbe :logic l :exec e)') and
 @('(ec-call (f t1 ... tk))') are effectively transformed by removing guard
 holders into @('l') and @('(f t1 ... tk)'), respectively.</p>

 <p>The final two classes of simplification above (removal of ``trivial''
 lambda applications) may be removed by executing the following form, which is
 @(tsee local) to an @(tsee encapsulate) form and to @(see books).</p>

 @({
 (defattach-system remove-guard-holders-lamp constant-nil-function-arity-0)
 })

 <p>Here is how to restore the default behavior.</p>

 @({
 (defattach-system remove-guard-holders-lamp constant-t-function-arity-0)
 })

 <p>Note that by default, guard-holders are not removed inside calls of @(tsee
 hide).  You can however cause them to be removed inside such calls after all,
 as was the case through Version  8.2, as follows.</p>

 @({
 (defattach-system ; generates (local (defattach ...))
   remove-guard-holders-blocked-by-hide-p
   constant-nil-function-arity-0)
 })")

(defxdoc guard-introduction
  :parents (guard)
  :short "Introduction to @(see guard)s in ACL2"
  :long "<p>Most users can probably profit by avoiding dealing with guards most
 of the time.  If they seem to get in the way, they can be ``turned off'' using
 the command @(':')@(tsee set-guard-checking) @('nil'); for more about this,
 see @(see set-guard-checking).  For more about guards in general, see @(see
 guard).</p>

 <p>The guard on a function symbol is a formula about the formals of the
 function.  To see the guard on a function, use the keyword command
 @(':')@(tsee args).  See @(see args).  To specify the guard on a function at
 @('defun-time'), use the @(':')@(tsee guard) @('xarg') (See @(see xargs)) or
 @('type') declarations (see @(see declare)).  The latter may be preferable if
 you want the host Lisp compiler to use this information.</p>

 <p>Guards can be seen as having either of two roles: (a) they are a
 specification device allowing you to characterize the kinds of inputs a
 function ``should'' have, or (b) they are an efficiency device allowing
 logically defined functions to be executed directly in Common Lisp.  Briefly:
 If the guards of a function definition are ``verified'' (see @(see
 verify-guards)), then the evaluation of a call of that function on arguments
 satisfying its guard will have the following property:</p>

 <blockquote><p>All subsequent function calls during that evaluation will be on
 arguments satisfying the guard of the called function.</p></blockquote>

 <p>The consequence of this fact for (a) is that your specification function is
 well-formed, in the sense that the values returned by this function on
 appropriate arguments only depend on the restrictions of the called functions
 to their intended domains.  The consequence of this fact for (b) is that in
 the ACL2 system, when a function whose guards have been verified is called on
 arguments that satisfy its guard, then the raw lisp function defined by this
 function's @(tsee defun) event is used to evaluate the call.  Note however
 that even when the user-supplied @(tsee defun) is not used, ACL2 uses a
 corresponding executable-counterpart function that generally performs, we
 expect, nearly as well as submitted function; see @(see evaluation) for
 relevant background on these two functions.  See @(see comp) to see how @(see
 compilation) can speed up both kinds of execution.</p>

 <p>Let us turn next to the issue of the relationship between guards and
 evaluation.  See @(see guards-and-evaluation).</p>")

(defxdoc guard-miscellany
  :parents (guard)
  :short "Miscellaneous remarks about guards"
  :long "<p>The discussion of guards concludes here with a few miscellaneous
 remarks.  (Presumably you found this documentation by following a link; see
 @(see guards-for-specification).)  For further information related to guards
 other than what you find under ``@(see guard),'' see any of the following
 documentation topics: @(see guard-example), @(tsee
 set-verify-guards-eagerness), @(tsee set-guard-checking), @(tsee
 verify-guards), and (for a discussion of keyword @(':split-types')) @(tsee
 xargs).</p>

 <p>@(tsee Defun) can be made to try to verify the guards on a function.  This
 is controlled by the ``@(see defun-mode)'' of the @(tsee defun); see @(see
 defun-mode).  The @(see defun-mode) is either as specified with the @(':mode')
 @('xarg') of the @(tsee defun) or else defaults to the default @(see
 defun-mode).  See @(see default-defun-mode).  If the @(see defun-mode) of the
 @(tsee defun) is @(':')@(tsee logic) and either a @(see guard) is specified
 explicitly or @(':')@(tsee verify-guards) @('t') is specified in the @(tsee
 xargs), then we attempt to verify the guards of the function.  Otherwise we do
 not.  (But see @(see set-verify-guards-eagerness) for how to modify this
 behavior.)</p>

 <p>It is sometimes impossible for the system to verify the guards of a
 recursive function at definition time.  For example, the guard conjectures
 might require the invention and proof of some inductively derived property of
 the function (as often happens when the value of a recursive call is fed to a
 guarded subroutine).  So sometimes it is necessary to define the function
 using @(':verify-guards nil') then to state and prove key theorems about the
 function, and only then have the system attempt guard verification.
 Post-@(tsee defun) guard verification is achieved via the event @(tsee
 verify-guards).  See @(see verify-guards).</p>

 <p>It should be emphasized that guard verification affects only two things:
 how fast ACL2 can evaluate the function and whether the function is executed
 correctly by raw Common Lisp, without guard violations.  Since ACL2 does not
 use the raw Common Lisp definition of a function to evaluate its calls unless
 that function's guards have been verified, the latter effect is felt only if
 you run functions in raw Common Lisp rather than via ACL2's command loop.</p>

 <p>Guard verification does not otherwise affect the theorem prover or the
 semantics of a definition.  If you are not planning on running your function
 on ``big'' inputs and you don't care if your function runs correctly in raw
 Common Lisp (e.g., you have formalized some abstract mathematical property and
 just happened to use ACL2 as your language), there is no need to suffer
 through guard verification.  Often users start by not doing guard verification
 and address that problem later.  Sometimes you are driven to it, even in
 mathematical projects, because you find that you want to run your functions
 particularly fast or in raw Common Lisp.</p>

 <p>Finally, we note that ACL2 collects up @(see guard)s from @(tsee declare)
 forms in order of appearance.  So for example, the @(tsee declare) form</p>

 @({
  (declare (xargs :guard (foo x))
           (type string x)
 })

 <p>will generate the guard @('(and (foo x) (stringp x))'), while the form</p>

 @({
  (declare (type string x)
           (xargs :guard (foo x))
 })

 <p>will generate the guard @('(and (stringp x) (foo x))').  The only
 exceptions to this rule are that all @(':stobjs') and @(':dfs') declarations
 will be treated as through they precede all @(':guard') and @('type')
 declarations.</p>")

(defxdoc guard-obligation
  :parents (guard-formula-utilities)
  :short "The guard proof obligation"
  :long "<p>See @(see verify-guards), and see @(see guard) for a discussion of
 guards.  @('Guard-obligation') is a low-level function for use in system
 programs, not typically appropriate for most ACL2 users.  A corresponding
 user-level utility is @(see verify-guards-formula); also see @(see
 guard-formula-utilities) for related utilities.</p>

 @({
  Example Forms:
  (guard-obligation 'foo nil t t 'top-level state)
  (guard-obligation '(if (consp x) (foo (car x)) t) nil nil t 'my-fn state)

  General Forms:
  (guard-obligation name rrp guard-debug guard-simplify ctx state)
  (guard-obligation term rrp guard-debug guard-simplify ctx state)
 })

 <p>where the first argument is either the name of a function or theorem or is
 a non-variable term that may be in untranslated form; @('rrp') (``return
 redundant p'') is non-@('nil') when it is permissible to return a value of
 @(''redundant') in the first (name) case (and is irrelevant in the term case);
 @('guard-debug') is typically @('nil') but may be @('t') (see @(see
 guard-debug)); @('guard-simplify') is typically @('t') but may be
 @(':limited') (see @(see verify-guards)); @('ctx') is a context (typically, a
 symbol used in error and warning messages); and @(tsee state) references the
 ACL2 @(see state).</p>

 <p>If you want to obtain the formula but you don't care about the so-called
 ``tag tree'':</p>

 @({
  (mv-let (erp val)
          (guard-obligation x nil guard-debug guard-simplify 'top-level state)
          (if erp
             ( .. code for handling error case, e.g., name is undefined .. )
            (let ((cl-set (cadr val))) ; to be proved for guard verification
              ( .. code using cl-set, which is a list of clauses,
                   implicitly conjoined, each of which is viewed as
                   a disjunction .. ))))
 })

 <p>The form @('(guard-obligation x rrp guard-debug guard-simplify ctx state)')
 evaluates to a pair @('(mv erp val)'), where @('erp') is @('nil') unless there
 is an error.  (Actually, this is a context-message pair; see the source code's
 ``Essay on Context-message Pairs''for relevant information.)  Suppose @('erp')
 is @('nil').  Then @('val') is the keyword @(':redundant') if the
 corresponding @(tsee verify-guards) event would be redundant and @('rrp') is
 not @('nil'); see @(see redundant-events).  Otherwise, @('val') is a tuple
 @('(list* names cl-set ttree)'), where: @('names') is @('(cons :term xt)') if
 @('x') is not a variable, where @('xt') is the translated form of @('x'); and
 otherwise is a list containing @('x') along with, if @('x') is defined in a
 @('mutual-recursion'), any other functions defined in the same @(tsee
 mutual-recursion) nest; @('cl-set') is a list of lists of terms, viewed as a
 conjunction of @(see clause)s (each viewed (as a disjunction); and @('ttree')
 is an assumption-free tag-tree that justifies cl-set.  (The notion of
 ``tag-tree'' may probably be ignored except for system developers.)</p>

 <p>@('Guard-obligation') is typically used for function names or non-variable
 terms, but as for @(tsee verify-guards), it may also be applied to theorem
 names.</p>

 <p>See the source code for @(tsee verify-guards-formula) for an example of how
 to use @('guard-obligation').</p>")

(defxdoc guard-quick-reference
  :parents (guard)
  :short "Brief summary of guard checking and guard verification"
  :long "<p>For a careful introduction to guards, see @(see guard).</p>

 <p><b>I. GUARD CHECKING DURING EXECUTION</b></p>

 <p><i>Effect</i></p>

 <p>Guards on definitions are checked at execution time (except for guards on
 subsidiary calls of recursive or mutually recursive functions).</p>

 <p><i>When does it happen</i></p>

 <p>By default, guards are checked for all forms submitted at the top
 level.</p>

 <p><i>To disable</i><br></br>

 @(':set-guard-checking nil') ; skip raw Lisp if there is a guard violation
 @(':set-guard-checking :none') ; skip guard checking entirely</p>

 <p><i>To (re-)enable</i><br></br>

 @(':set-guard-checking t')</p>

 <p>See @(see set-guard-checking) for more options.</p>

 <p><b>II. GUARD VERIFICATION</b></p>

 <p><i>Effect</i></p>

 <p>A proof is attempted of the obligations arising from the guards of
 subsidiary functions in a @(tsee defun), @(tsee defthm), or @(tsee defaxiom)
 event.  In the case of a @('defun'), the guard itself is also verified (under
 an implicit guard of @('t')).</p>

 <p><i>When does it happen</i></p>

 <p>Only names of defined functions, @(tsee defthm)s, and @(tsee defaxiom)s are
 subject to guard verification.  Guard verification may occur when functions
 are defined (using @(tsee defun)), but it requires an explicit call of @(tsee
 verify-guards) in order to verify guards for @(tsee defthm)s and @(tsee
 defaxiom)s.  Constrained functions (see @(see encapsulate)) may not have their
 guards verified.</p>

 <p>@('(verify-guards foo ...)')<br></br>

 causes guard verification for the @(tsee defun), @(tsee defthm), or @(tsee
 defaxiom) named by @('foo'), if it has not already been successfully done.
 The default @(see defun-mode) (see @(see default-defun-mode)) must be
 @(':')@(tsee logic), or else this event is ignored.</p>

 <p>@('(defun foo ...)')<br></br>

 causes guard verification of @('foo') if and only if the following two
 conditions are both met.  First, foo is processed in @(':')@(tsee logic)
 mode (either by setting mode @(':')@(tsee logic) globally, or by including
 @(':mode :logic') in the @(tsee xargs) declaration).  Second, at least one of
 the following sub-conditions is met.  Also see @(see xargs), and see @(see
 set-verify-guards-eagerness) for how to change this behavior.</p>

 <blockquote><p>1. The @(tsee xargs) declaration specifies a @(':')@(tsee
 guard).</p>

 <p>2. There is at least one @('type') declaration (see @(see declare)).</p>

 <p>3. The @(tsee xargs) declaration specifies @(':')@(tsee stobj)@('s').</p>

 <p>4. The @(tsee xargs) declaration specifies @(':')@(tsee verify-guards)
 @('t').</p></blockquote>

 <p>@('(verify-termination foo ...)')<br></br>

 causes guard verification of @('foo') if @('foo') is a function currently
 defined in @(':')@(tsee program) mode and the criteria for guard verification
 of a @(tsee defun) form are met, as discussed above.  The default @(see
 defun-mode)
 (see @(see default-defun-mode)) must be @(':')@(tsee logic), or else this
 event is ignored.</p>")

(defxdoc guard-simplification
  :parents (guard-formula-utilities)
  :short "Levels of simplification for @(see guard) proof obligations"
  :long "<p>ACL2 provides several features for obtaining the proof obligations
 generated for @(see guard) verification.  Each of these features can be
 invoked with an argument that controls the level of simplification to be
 applied before returning those proof obligations.  This topic examines those
 simplification levels.  It starts by splitting the features into two groups;
 then continues by explaining the three levels of simplification; and finally,
 makes the key point that one group allows the top two levels of simplification
 and the other group allows the bottom two levels.</p>

 <p>These features can be partitioned into two groups, which we reference below
 as the ``<b>AT</b>'' and ``<b>AFTER</b>'' groups, as follows.  These
 correspond respectively to the two groups discussed in the documentation
 topic, @(see guard-formula-utilities), for capturing formulas produced either
 during guard verification or when a @(':guard-theorem') is supplied for a
 @(':use') hint.</p>

 <ul>

 <li>Simplification <b>AT</b> guard-verification time:<br/>

 <ul>

 <li>the @(tsee xargs) keyword @(':guard-simplify'),</li>

 <li>the @(tsee guard-obligation) utility, and</li>

 <li>the @(tsee verify-guards-formula) utility.</li>

 </ul></li>

 <li>Simplification <b>AFTER</b> guard-verification time:<br/>

 <ul>

 <li>the @(':')@(tsee gthm) utility, and</li>

 <li>the @(':')@(tsee guard-theorem) @(see lemma-instance) (and related
 low-level utility, @('guard-theorem').</li>

 </ul></li>

 </ul>

 <p>Each feature above has an argument (possibly optional) that controls the
 level of simplification.  Each such argument can take any of three values, as
 follows.  But <b>NOTE</b>: @('T') and @(':LIMITED') are the only legal values
 for the &ldquo;AT&rdquo; (first) group, and @(':LIMITED') and @('NIL') are the
 only legal values for the &ldquo;AFTER'' (second) group.</p>

 <ul>

 <li>@('T'):<br/>
 Full simplification, which is the default behavior for @(tsee
 verify-guards)</li>

 <li>@(':LIMITED'):<br/>
 Reduced simplification, skipping simplifications that depend on the set of
 currently @(see enable)d rules</li>

 <li>@('NIL'):<br/>
 No simplification</li>

 </ul>

 <p>The key point of this topic is the following specification of the values
 allowed for the simplification argument, for the features in each group.  For
 features in the <b>AT</b> group, @('T') and @(':LIMITED') are the legal
 values.  For features in the <b>AFTER</b> group, @(':LIMITED') and @('NIL')
 are the legal levels.  Let's see why this is reasonable and discuss whether
 the missing value for each group might be allowed in the future.</p>

 <p>First consider the <b>AFTER</b> group.  A @(':')@(tsee guard-theorem)
 @(':use') hint obtains the @(see guard) theorem proved for a previously
 guard-verified function.  The @(tsee current-theory) at the time of that
 @(':use') hint may be very different from what it was at guard-verification
 time.  Thus, when processing that hint it would be misleading to allow the
 current @(see theory) to participate in simplification that produces the guard
 theorem, since the result could be very different from the guard theorem
 generated during the earlier guard verification.  That is why the value @('T')
 is not allowed for the simplification argument of a @(':')@(tsee
 guard-theorem) hint.  Instead, the default is @(':LIMITED').  The @(tsee gthm)
 utility provides a way to show the formula that would be provided by a
 @(':guard-theorem') lemma instance, so @('gthm') also disallows @('T'), and
 its default is also @(':LIMITED').  Note that the utility @(tsee
 verify-guards-formula) is more appropriate than @('gthm') to view the formula
 to be proved if one is about to verify guards for a function.  (If @('gthm')
 were to be used for that purpose too, then @('T') might be allowed as a
 simplification argument; but that could lead to confusion, in particular about
 the default.)</p>

 <p>Now consider the <b>AT</b> group, which relates to guard verification.
 @('T') is a reasonable default: it is generally useful to maximize
 simplification while generating the guard theorem before attempting its proof.
 But one may prefer more control, by avoiding simplification until the proof is
 attempted.  @(':LIMITED') has proved to be a good compromise: it limits
 simplification to basic operations, in particular avoiding goals that are
 subsumed by other goals or are instances of trivial @(see built-in-clause)
 rules.  If the need arises to support @('NIL') as a simplification value,
 perhaps ACL2 will change to support that.</p>")

(defxdoc guard-theorem
  :parents (lemma-instance guard-formula-utilities hints)
  :short "Use a previously-proved @(see guard) theorem"
  :long "<p>See @(see lemma-instance) for a discussion of @(':guard-theorem')
 lemma instances, as illustrated in the topic @(see guard-theorem-example).</p>

 <p>The function @('guard-theorem') is a low-level system utility that returns
 a translated @(see term).  It is essentially the functional version of the
 @('gthm') macro, which however returns an untranslated term.  See @(see
 gthm).</p>")

(defxdoc guard-theorem-example
  :parents (lemma-instance guard
    hints
    guard-theorem
    guard-formula-utilities)
  :short "How to use a previously-proved @(see guard) theorem"
  :long "<p>See @(see lemma-instance) for a discussion of @(':guard-theorem')
 lemma instances, and see @(see gthm) for a related user-level query utility.
 In this topic, we illustrate the use of such lemma instances to take advantage
 of a @(see guard) theorem already proved for an existing definition, when
 attempting to admit a new definition.</p>

 <p>The following example is contrived but should get the idea across.  Suppose
 that the event displayed just below was previously executed, for example when
 including a book.  The @(tsee mbe) call generates a guard proof obligation,
 but there is only one thing to know about that for this example: without the
 local lemma shown, the guard proof fails for @('f1').</p>

 @({
 (encapsulate
   ()
   (local (defthm append-revappend
            (equal (append (revappend x y) z)
                   (revappend x (append y z)))))

   (defun f1 (x y)
     (declare (xargs :guard (and (true-listp x)
                                 (true-listp y))))
     (mbe :logic (append (reverse x) y)
          :exec (revappend x y))))
 })

 <p>Now suppose that later, we wish to admit a function with the same guard and
 body.  Since the lemma @('append-revappend') above is @(see local), guard
 verification will likely fail.  However, we can tell the prover to use the
 guard theorem already proved for @('f1'), as follows; then the guard
 verification proof succeeds.</p>

 @({
 (defun f2 (x y)
   (declare (xargs :guard (and (true-listp x)
                               (true-listp y))
                   :guard-hints (("Goal" :use ((:guard-theorem f1))))))
   (mbe :logic (append (reverse x) y)
        :exec (revappend x y)))
 })

 <p>See @(see termination-theorem-example) for an example use of the analogous
 lemma instance type, @(':termination-theorem').  That topic also includes
 discussion of the use of event names in prover output.</p>")

(defxdoc guards-and-evaluation
  :parents (guard)
  :short "The relationship between guards and evaluation"
  :long "<p>For relevant background see @(see evaluation).</p>

 <p>The guard has no effect on the logical axiom added by the
 definition of a function.  It does, however, have consequences for how calls
 of that function are evaluated in ACL2.  We begin by explaining those
 consequences, when ACL2 is in its default ``mode,'' i.e., as originally
 brought up.  In subsequent discussion we'll consider other ways that guards
 can interact with evaluation.</p>

 <p>For more about guards in general, see @(see guard).  For in-depth
 discussion of the interaction between the @(see defun-mode) and guard
 checking, see @(see set-guard-checking), see @(see guard-evaluation-table),
 see @(see guard-evaluation-examples-script), and see @(see
 guard-evaluation-examples-log).  Also see @(see generalized-booleans) for
 discussion about a subtle issue in the evaluation of certain Common Lisp
 functions.</p>

 <p><i>Guards and evaluation I: the default</i></p>

 <p>Consider the following very simple definition.</p>

 @({
  (defun foo (x) (cons 1 (cdr x)))
 })

 <p>First consider how raw Common Lisp behaves when evaluating calls of this
 function.  To evaluate @('(foo x)') for some expression @('x'), first @('x')
 is evaluated to some value @('v'), and then @('(cons 1 (cdr x))') is evaluated
 with @('x') bound to @('v').  For example, if @('v') is @('(cons 'a 3)'), then
 Common Lisp computes @('(cons 1 3)').  But if (for example) @('v') is a
 number, e.g., @('7'), then there is no way to predict what Common Lisp might
 do.  Some implementations would cause ``sensible'' errors, others might return
 nonsense, still others might crash the host machine.  The results tend toward
 the catastrophic if the call of @('foo') in question is in compiled code.</p>

 <p>Now by default, ACL2 evaluates calls of @('foo') exactly as Common Lisp
 does, except that it uses guards to check the ``legality'' of each function
 call.  So for example, since @('(cdr x)') has a guard of @('(or (consp x)
 (equal x nil))'), the call @('(foo 7)') would cause a ``guard violation,'' as
 illustrated below.</p>

 @({
  ACL2 !>(foo 7)

  ACL2 Error in TOP-LEVEL:  The guard for the function symbol CDR, which
  is (OR (CONSP X) (EQUAL X NIL)), is violated by the arguments in the
  call (CDR 7).

  ACL2 !>
 })

 <p>Thus, the relation between evaluation in ACL2 and evaluation in Common Lisp
 is that the two produce the very same results, provided there is no guard
 violation.</p>

 <p><i>Guards and evaluation II:</i> @(':')@(tsee set-guard-checking).</p>

 <p>The ACL2 logic is a logic of total functions.  That is, every application
 of a function defined has a completely specified result.  See the @(see
 documentation) for each individual primitive for the specification of what it
 returns when its guard is violated; for example, see @(see cdr).</p>

 <p>The presence of guards thus introduces a choice in the sense of evaluation.
 When you type a form for evaluation do you mean for guards to be checked or
 not?  Put another way, do you mean for the form to be evaluated in Common Lisp
 (if possible) or in the ACL2 logic?  Note: If Common Lisp delivers an answer,
 it will be the same as in the logic, but it might be erroneous to execute the
 form in Common Lisp.  For example, the ACL2 logic definition of @(tsee cdr)
 implies that the @(tsee cdr) of an @(see atom) is @('nil'); see @(see cdr).
 So: should @('(cdr 7)') cause a guard violation error or return @('nil')?</p>

 <p>The top-level ACL2 loop has a variable which controls which sense of
 execution is provided.  By default, ``guard checking'' is on, by which we mean
 that guards are checked at runtime, in the sense already described.  To allow
 execution to proceed in the logic when there is a guard violation, do
 @(':')@(tsee set-guard-checking)@(' nil'); or evaluate @(':')@(tsee
 set-guard-checking)@(' :none') to skip guard checking entirely.  To turn
 ``guard checking'' back on, execute the top-level form @(':')@(tsee
 set-guard-checking)@(' t').  The status of guard checking reflected in the
 @(see prompt); guard-checking is ``on'' when the @(see prompt) contains an
 exclamation mark (also see @(see default-print-prompt)).  For example,</p>

 @({
  ACL2 !>
 })

 <p>means guard checking is on and</p>

 @({
  ACL2 >
 })

 <p>means guard checking is off.  The exclamation mark can be thought of as
 ``barring'' certain computations.  The absence of the mark suggests the
 absence of error messages or unbarred access to the logical axioms.  Thus, for
 example</p>

 @({
  ACL2 !>(car 'abc)
 })

 <p>will signal an error, while</p>

 @({
  ACL2 >(car 'abc)
 })

 <p>will return @('nil').  To return to our previous example: with guard
 checking off, @('(foo 7)') evaluates to @('(cons 1 nil)').  Also see @(see
 set-guard-checking).</p>

 <p><i>Guards and evaluation III: guard verification</i></p>

 <p>Consider the definition of @('foo') given above, but modified so that a
 reasonable guard of @('(consp x)') is specified, as shown below.</p>

 @({
  (defun foo (x)
    (declare (xargs :guard (consp x)))
    (cons 1 (cdr x)))
 })

 <p>We say ``reasonable guard'' above because if @('x') is such that @('(consp
 x)') holds, then the call of @(tsee cdr) in the evaluation of @('(foo x)')
 will not cause a guard violation.  Thus, it ``should'' be legal to evaluate
 @('(foo x)'), for any such @('x'), simply by evaluating this form in raw
 Common Lisp.</p>

 <p>The @(tsee verify-guards) event has been provided for this purpose.
 Details may be found elsewhere; see @(see verify-guards).  Briefly, for any
 defined function @('fn'), the event @('(verify-guards fn)') attempts to check
 the condition discussed above, that whenever @('fn') is called on arguments
 that satisfy its guard, the evaluation of this call will proceed without any
 guard violation.  (Moreover, the guard itself should be evaluable without any
 guard violation.)  If this check is successful, then future calls of this sort
 will be evaluated in raw Common Lisp.</p>

 <p>Returning to our example above, the @('(verify-guards foo)') will succeed
 because the guard @('(consp x)') of @('foo') implies the guard generated from
 the call @('(cdr x)') in the body of the definition, namely, @('(or (consp x)
 (equal x nil))') (see @(see cdr)).  Then the evaluation of @('(foo (cons 'a
 3))') will take place in raw Common Lisp, because @('(cons 'a 3)') satisfies
 the guard of @('foo').</p>

 <p>This ability to dive into raw Common Lisp hinges on the proof that the
 guards you attach to your own functions are sufficient to ensure that the
 guards encountered in the body are satisfied.  This is called ``guard
 verification.'' Once a function has had its guards verified, then ACL2 can
 evaluate the function somewhat faster (but see ``Guards and evaluation V:
 efficiency issues'' below).  Perhaps more importantly, ACL2 can also guarantee
 that the function will be evaluated correctly by any implementation of Common
 Lisp (provided the guard of the function is satisfied on the input).  That is,
 if you have verified the guards of a system of functions and you have
 determined that they work as you wish in your host ACL2 (perhaps by proving
 it, perhaps by testing), then they will work identically in any Common
 Lisp.</p>

 <p>There is a subtlety to our treatment of evaluation of calls of functions
 whose guards have been verified.  If the function's guard is not satisfied by
 such a call, then no further attempt is made to evaluate any call of that
 function in raw lisp during the course of evaluation of that call.  This is
 obvious if guard checking is on, because an error is signaled the first time
 its guard is violated; but in fact it is also true when guard checking is off.
 See @(see guard-example) for an example.</p>

 <p><i>Guards and evaluation IV: functions having :program mode</i></p>

 <p>Strictly speaking, functions in @(':')@(tsee program) mode (see @(see
 defun-mode)) do not have definitions in the ACL2 logic.  So what does it mean
 to evaluate calls of such functions in ACL2?  In general we treat @(':')@(tsee
 program) functions much as we treat @(':')@(tsee logic) functions whose guards
 have been verified, except that when no error occurs then the corresponding
 raw Lisp function is always called.  (We say ``in general'' because there are
 exceptions, discussed in the ``Aside'' just below.)  Note that when the guard
 of a function in @(':')@(tsee logic) mode is violated, there is still a value
 that the ACL2 logic proves is equal to the given call.  But the same cannot be
 said for a function in @(':')@(tsee program) mode.  Nevertheless, for the sake
 of convenience we go ahead and evaluate the corresponding raw Lisp function
 except in the situation where the guard is violated and guard-checking is on,
 aside from the following:</p>

 <p><b>Aside</b>.  There are exceptions to the use of raw Lisp, discussed just
 above, to evaluate calls of @(':')@(tsee program) mode functions.  The primary
 one is that after @(':')@(tsee set-guard-checking)@(' :none'), evaluation of
 user-defined @(':')@(tsee program) mode function calls is done in the ACL2
 logic, not in raw Lisp.  The more obscure exception is that during expansion
 of macros and @(tsee make-event) forms, and during evaluation of @(tsee
 defconst) forms, ACL2 enters a ``safe mode'' in which this escape to raw Lisp
 is prevented.  The following example illustrates how the user can experiment
 directly with safe mode, though it is preferred to use @(':')@(tsee
 set-guard-checking)@(' :none') if you are happy to skip all guard checking and
 evaluate forms in the logic.</p>

 @({
  ACL2 !>(defun foo (x)
           (declare (xargs :mode :program :guard t))
           (car x))

  Summary
  Form:  ( DEFUN FOO ...)
  Rules: NIL
  Warnings:  None
  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
   FOO
  ACL2 !>(foo 3)
  Error: Attempt to take the car of 3 which is not listp.
    [condition type: SIMPLE-ERROR]

  Restart actions (select using :continue):
   0: Return to Top Level (an "abort" restart).
   1: Abort entirely from this process.
  [1] ACL2(2): :pop
  ACL2 !>(assign safe-mode t)
   T
  ACL2 !>(foo 3)

  ACL2 Error in TOP-LEVEL:  The guard for the function symbol CAR, which
  is (OR (CONSP X) (EQUAL X NIL)), is violated by the arguments in the
  call (CAR 3).  See :DOC trace for a useful debugging utility.  See
  :DOC set-guard-checking for information about suppressing this check
  with (set-guard-checking :none), as recommended for new users.

  ACL2 !>(assign safe-mode nil)
   NIL
  ACL2 !>(foo 3)
  Error: Attempt to take the car of 3 which is not listp.
    [condition type: SIMPLE-ERROR]

  Restart actions (select using :continue):
   0: Return to Top Level (an "abort" restart).
   1: Abort entirely from this process.
  [1] ACL2(2):
 })

 <p>The other exception occurs after @(tsee set-guard-checking) can be called
 with a value of @(':all'); see @(see set-guard-checking).  <b>End of
 aside.</b></p>

 <p>Thus, as with @(':')@(tsee logic) functions: when a guard has been
 satisfied on a call of a function with @(':')@(tsee program) mode, no
 subsidiary guard checking will be done.</p>

 <p>Notice that by treating functions in @(':')@(tsee program) mode like
 functions whose guards have been verified, we are using raw lisp to compute
 their values when their guards are met.  We do not check guards any further
 once raw lisp is invoked.  This can lead to hard lisp errors if the guards are
 not appropriate, as illustrated below.</p>

 @({
  ACL2 >:program
  ACL2 p>(defun foo (x)
          (declare (xargs :guard t))
          (cons 1 (cdr x)))

  Summary
  Form:  ( DEFUN FOO ...)
  Rules: NIL
  Warnings:  None
  Time:  0.02 seconds (prove: 0.00, print: 0.00, proof tree: 0.00, other: 0.02)
   FOO
  ACL2 p>(foo 3)

  Error: 3 is not of type LIST.
  Fast links are on: do (use-fast-links nil) for debugging
  Error signalled by CDR.
  Broken at COND.  Type :H for Help.
  ACL2>>
 })

 <p>See @(see defun-mode-caveat).</p>

 <p>However, here is a way to get ACL2 to do run-time guard checking for
 user-defined @(':')@(tsee program) mode functions.  With this method, ACL2
 will evaluate calls of user-defined @(':program') mode functions in a manner
 that follows their ACL2 definitions.  Simply execute the following in the ACL2
 loop to put ACL2 into a ``safe mode.''</p>

 @({
  (f-put-global 'safe-mode t state)
 })

 <p>Let us revisit the example above, using safe mode.  Notice that the guard
 of @(tsee cdr) is now being checked, because the executable-counterpart of
 @('foo') is being called even though the @(see guard) is @('t').</p>

 @({
  ACL2 !>(f-put-global 'safe-mode t state)
  <state>
  ACL2 !>:program
  ACL2 p!>(defun foo (x)
            (declare (xargs :guard t))
            (cons 1 (cdr x)))

  Summary
  Form:  ( DEFUN FOO ...)
  Rules: NIL
  Warnings:  None
  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
   FOO
  ACL2 p!>(foo 3)

  ACL2 Error in TOP-LEVEL:  The guard for the function symbol CDR, which
  is (OR (CONSP X) (EQUAL X NIL)), is violated by the arguments in the
  call (CDR 3).  See :DOC trace for a useful debugging utility.  See
  :DOC set-guard-checking for information about suppressing this check
  with (set-guard-checking :none), as recommended for new users.

  ACL2 p!>
 })

 <p>If we go back into ``unsafe'' mode, then we once again see a raw Lisp
 error, as we now illustrate.</p>

 @({
  ACL2 p!>(f-put-global 'safe-mode nil state)
  <state>
  ACL2 p!>(foo 3)

  Error: 3 is not of type LIST.
  Fast links are on: do (si::use-fast-links nil) for debugging
  Error signalled by CDR.
  Broken at COND.  Type :H for Help.
  ACL2>>
 })

 <p><i>Guards and evaluation V: efficiency issues</i></p>

 <p>We have seen that by verifying the guards for a @(':')@(tsee logic)
 function, we arrange that raw lisp is used for evaluation of calls of such
 functions when the arguments satisfy its guard.</p>

 <p>This has several apparent advantages over the checking of guards as we go.
 First, the savings is magnified as your system of functions gets deeper: the
 guard is checked upon the top-level entry to your system and then raw Common
 Lisp does all the computing.  Second, if the raw Common Lisp is compiled (see
 @(see compilation)), enormous speed-ups are possible.  Third, if your Common
 Lisp or its compiler does such optimizations as @('tail-recursion') removal,
 raw Common Lisp may be able to compute your functions on input much ``bigger''
 than ACL2 can.</p>

 <p>The first of these advantages is quite important if you have complicated
 guards.  However, the other two advantages are probably not very important, as
 we now explain.</p>

 <p>When a function is defined in @(':')@(tsee logic) mode, its @(tsee defun)
 is executed in raw Common Lisp; we call this the ``submitted'' definition of
 the function.  However, a corresponding executable-counterpart also
 executed.  (See @(see evaluation) for an introduction to submitted and
 executable-counterpart definitions.)  The executable-counterpart is a @(tsee
 defun) in raw lisp that checks guards at runtime and escapes to the submitted
 definition if the guard holds of the arguments and the function has already
 had its guards verified.  Otherwise the executable-counterpart evaluates the
 body of the function by calling the executable-counterpart of each subroutine.
 Now it is true that @(see compilation) often speeds up execution
 significantly.  However, the @(':')@(tsee comp) command (see @(see comp))
 compiles both of the raw lisp definitions associated with a function.  Also,
 we have attempted to arrange that for every tail recursion removal done on the
 actual @(tsee defun), a corresponding tail recursion removal is done on the
 executable-counterpart definition.</p>

 <p>We believe that in most cases, the executable-counterpart executes almost
 as fast as the submitted definition, at least if the evaluation of the guards
 is fast.  So, the main advantage of guard verification is probably that it
 lets you know that the submitted function may be executed safely in raw lisp,
 returning the value predicted by the ACL2 logic, whenever its arguments
 satisfy its guard.  We envision the development of systems of applicative lisp
 functions that have been developed and reasoned about using ACL2 but which are
 intended for evaluation in raw Common Lisp (perhaps with only a small ``core''
 of ACL2 loaded), so this advantage of guard verification is important.</p>

 <p>Nevertheless, guard verification might be important for optimal efficiency
 when the functions make use of type declarations.  For example, at this
 writing, the GCL implementation of Common Lisp can often take great advantage
 of @(tsee declare) forms that assign small integer types to formal parameters.
 Note that while type declarations contributed to the guard by default, they
 can be proved from the guard instead; see @(see xargs) for a discussion of the
 @(':split-types') keyword.</p>

 <p>To continue the discussion of guards, see @(see guards-for-specification)
 to read about the use of guards as a specification device.</p>")

(defxdoc guards-for-specification
  :parents (guard)
  :short "Guards as a specification device"
  :long "<p>A use of guard verification that has nothing to do with efficiency
 is as a way to gain confidence in specifications.  This use has the feel of
 ``types'' in many traditional @(see programming) languages, though guards
 allow much greater expressiveness than most systems of types
 (and unfortunately, as a result they are not syntactically checkable).</p>

 <p>For more discussion of guards in general, see @(see guard).</p>

 <p>Suppose you have written a collection of function definitions that are
 intended to specify the behavior of some system.  Perhaps certain functions
 are only intended to be called on certain sorts of inputs, so you attach
 guards to those functions in order to ``enforce'' that requirement.  And then,
 you verify the guards for all those functions.</p>

 <p>Then what have you gained, other than somewhat increased efficiency of
 execution (as explained above), which quite possibly isn't your main concern?
 You have gained the confidence that when evaluating any call of a
 (specification) function whose arguments satisfy that function's guard, all
 subsequent function calls during the course of evaluation will have this same
 property, that the arguments satisfy the guard of the calling function.</p>

 <p>The rest of this topic addresses those who wish to understand @(see guard)s
 from a proof-theoretic perspective instead of (or in addition to) the
 evaluation perspective given above.  In logical terms, we can say that the
 equality of the original call with the returned value is provable from
 weakened versions of the definitions, where each definitional axiom is
 replaced by an implication whose antecedent is the requirement that the
 arguments satisfy the guard and whose consequent is the original axiom.  For
 example,</p>

 @({
  (defun foo (x)
    (declare (xargs :guard (consp x)))
    (cons 1 (cdr x)))
 })

 <p>originally generates the axiom</p>

 @({
  (equal (foo x)
         (cons 1 (cdr x)))
 })

 <p>but in fact, when evaluation involves no guard violation then the following
 weaker axiom suffices in the justification of the evaluation.</p>

 @({
  (implies (consp x)
           (equal (foo x)
                  (cons 1 (cdr x))))
 })

 <p>So for example, suppose we evaluate @('(foo '(a b c))') and get @(''(1 b
 c)').  Then of course the equality of these two terms is provable from the
 original axiom.  The point here is that it's even provable from the weaker
 axiom.</p>

 <p>If you are following links to read this documentation as a hypertext style
 document, then please see @(see guard-miscellany).  This concludes our
 discussion of guards with miscellaneous remarks, and also contains pointers to
 related topics.</p>")

(defxdoc |Guards in ACL2|
  :parents (|Pages Written Especially for the Tours|)
  :short "Guards"
  :long "<p>Common Lisp functions are partial; they are not defined for all
 possible inputs.  But ACL2 functions are total.  Roughly speaking, the logical
 function of a given name in ACL2 is a <b>completion</b> of the Common Lisp
 function of the same name obtained by adding some arbitrary but ``natural''
 values on arguments outside the ``intended domain'' of the Common Lisp
 function.</p>

 <p>ACL2 requires that every ACL2 function symbol have a ``guard,'' which may
 be thought of as a predicate on the formals of the function describing the
 intended domain.  The guard on the primitive function @(tsee car) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>,
 for example, is @('(or (consp x) (equal x nil))'), which requires the argument
 to be either an ordered pair or @('nil').  We will discuss later how to
 specify a guard for a defined function; when one is not specified, the guard
 is @('t') which is just to say all arguments are allowed.</p>

 <p><b>But guards are entirely extra-logical</b>: they are not involved in the
 axioms defining functions.  If you put a guard on a defined function, the
 defining axiom added to the logic defines the function on <b>all</b>
 arguments, not just on the guarded domain.</p>

 <p>So what is the purpose of guards?</p>

 <p>The key to the utility of guards is that we provide a mechanism, called
 ``guard verification,'' for checking that all the guards in a formula are
 true.  See @(see verify-guards).  This mechanism will attempt to prove that
 all the guards encountered in the evaluation of a guarded function are true
 every time they are encountered.</p>

 <p>For a thorough discussion of guards, see the paper [km97] in the ACL2 @(see
 bibliography).</p>")

(defxdoc |Guessing the Type of a Newly Admitted Function|
  :parents (|Pages Written Especially for the Tours|)
  :short "Guessing the Type of a Newly Admitted Function"
  :long "<p>When a function is admitted to the logic, ACL2 tries to ``guess''
 what type of object it returns.  This guess is codified as a term that
 expresses a property of the value of the function.  For @('app') the term
 is</p>

 @({
  (OR (CONSP (APP X Y))
      (EQUAL (APP X Y) Y))
 })

 <p>which says that @('app') returns either a cons or its second argument.
 This formula is added to ACL2's rule base as a @(tsee type-prescription) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>
 rule.  Later we will discuss how rules are used by the ACL2 theorem prover.
 The point here is just that when you add a definition, the database of rules
 is updated, not just by the addition of the definitional axiom, but by several
 new rules.</p>

 <p>You should now return to <see topic='@(url
 |Revisiting the Admission of App|)'>the Walking Tour</see>.</p>")

(defxdoc |Guiding the ACL2 Theorem Prover|
  :parents (|Pages Written Especially for the Tours|)
  :short "Guiding the ACL2 Theorem Prover"
  :long "<p><see topic='@(url
 |ACL2 as an Interactive Theorem Prover (cont)|)'><img
 src='res/tours/walking.gif'></img></see></p>

 <p>Now that you have seen the theorem prover in action you might be curious as
 to how you guide it.</p>

 <p><img src='res/tours/interactive-theorem-prover.gif'></img></p>

 <p>Look at the picture above.  It is meant to suggest that <i>Q</i> is an
 important lemma needed for the proof of <i>P</i>.  Note that to lead the
 prover to the proof of <i>P</i> the user first proves <i>Q</i>.  In a way, the
 formulation and proof of <i>Q</i> is a hint to the prover about how to prove
 <i>P</i>.</p>

 <p>The user usually doesn't think of <i>Q</i> or recognize the need to prove
 it separately until he or she sees the theorem prover <b>fail</b> to prove
 <i>P</i> without it ``knowing'' <i>Q</i>.</p>

 <p>The way the user typically discovers the need for <i>Q</i> is to look at
 failed proofs.</p>

 <p><see topic='@(url |ACL2 as an Interactive Theorem Prover (cont)|)'><img
 src='res/tours/walking.gif'></img></see></p>")

(defxdoc hands-off-lambda-objects-theory
  :parents (theories theory-functions rewrite)
  :short "how to specify no modification of lambda objects"
  :long "<p>The enabled status of two @('rewrite-lambda-modep') runes are used
  as flags to determine the action taken when eligible @('lambda') objects are
  encountered by the ACL2 rewriter.  See @(see rewrite-lambda-object) and
  @(tsee rewrite-lambda-object-actions).  To prevent the rewriter even
  considering changing a quoted @('lambda') object, the rune
  @('(:executable-counterpart rewrite-lambda-modep)') must be disabled in the
  then-current theory.  The 0-ary function @('hands-off-lambda-objects-theory')
  returns such a theory.</p>

  <p>In fact, diving into eligible quoted @('lambda') object constants to
  rewrite the body is the default action when ACL2 starts up.  See @(see
  rewriting-versus-cleaning-up-lambda-objects) for why you might want to change
  the default action when eligible @('lambda') objects are encountered by the
  rewriter.</p>

  <p>The expression @('(hands-off-lambda-objects-theory)') macroexpands to the
  theory expression</p>

  @({
  (e/d nil
       ((:executable-counterpart rewrite-lambda-modep)))
  })

  <p>which is a theory equal to the current theory except that the
  executable-counterpart rune of @('rewrite-lambda-modep') is disabled.  This
  expansion is suitable for use in an @(tsee in-theory) event or
  @(':in-theory') hint (see @(':')@(tsee hints)).</p>

  <p>This rune is initially enabled, so eligible @('lambda') object bodies are
  either rewritten or syntactically cleaned by default (depending on the status
  of @('(:definition rewrite-lambda-modep)')) until and unless some
  event (e.g., an @(tsee in-theory) or @(tsee include-book)) or a superior
  local subgoal hint changes the status of this rune.</p>

  <p>For example, if @('lambda') object rewriting is active and you wish it not
  to be (so that @('lambda') objects remain unchanged) in @('Subgoal 3') of
  some proof, you could use the @(':')@(tsee hints)</p>

  @({
  ("Subgoal 3"
   :in-theory (hands-off-lambda-objects-theory))
  })

  <p>Note that if you also wish to enable or disable other runes in the same
  subgoal you must construct an appropriate theory.</p>

  <p>For example, if in @('Subgoal 3') of some proof you wanted to enable
  @('LEMMA1') and disable @('LEMMA2') in a theory that will also specify
  syntactic cleaning of @('lambda') objects, you might write</p>

  @({
  ("Subgoal 3"
   :in-theory (set-difference-theories
                 (union-theories (hands-off-lambda-objects-theory)
                                 '(LEMMA1))
                 '(LEMMA2)))
  })

  <p>Some users might prefer</p>

  @({
  ("Subgoal 3"
   :in-theory (e/d (LEMMA1)
                   ((:executable-counterpart rewrite-lambda-modep)
                    LEMMA2)))
  })

  <p>See @(see theories) for general information about theories and how to
  create and use them.</p>")

(defxdoc hard-error
  :parents (errors acl2-built-ins)
  :short "Print an error message and stop execution"
  :long "<p>@('(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 @(tsee fmt).  See @(see fmt).  Also see @(see er) for a
 macro that provides a unified way of signaling errors.</p>

 <p>@('Hard-error') has a guard of @('t').  Also see @(see illegal) for a
 similar capability which however has a guard of @('nil') that supports static
 checking using @(tsee guard) verification, rather than using dynamic
 (run-time) checking.  This distinction is illustrated elsewhere: see @(see
 prog2$) for examples.</p>

 <p>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 @(tsee fmt)), after which evaluation halts immediately.
 Here is a trivial, contrived example.</p>

 @({
  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 !>
 })

 <p>Technical note for raw Lisp programmers only.  It is possible to cause hard
 errors to signal actual raw Lisp errors, simply by evaluating the following
 form in raw Lisp: @('(setq *hard-error-is-error* t)').  Indeed, any
 non-@('nil') value for @('*hard-error-is-error*') will cause @('hard-error')
 or @(tsee illegal) &mdash; or indeed @('(er hard ...)'), @('(er hard! ...)'),
 or @('(er hard?  ...)') &mdash; to produce a Lisp error whose condition, when
 printed with @('format') directive @('~a'), is the same error message that
 ACL2 would otherwise print.  Below is a sample log, closely based on an
 example provided by Jared Davis.</p>

 @({
  ACL2 !>(defun f (x)
           (er hard 'f "F got bad input ~x0.~%" x))

  Since F is non-recursive, its admission is trivial.  We observe that
  the type of F is described by the theorem (EQUAL (F X) NIL).  We used
  the :type-prescription rule ILLEGAL.

  Summary
  Form:  ( DEFUN F ...)
  Rules: ((:TYPE-PRESCRIPTION ILLEGAL))
  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
   F
  ACL2 !>:q

  Exiting the ACL2 read-eval-print loop.  To re-enter, execute (LP).
  ? (defun run-f ()
      (let ((*hard-error-is-error* t))
        (handler-case
         (f 3)
         (error (condition)
                (format t "Got the following error: ~a~%" condition)))))
  RUN-F
  ? (run-f)
  Got the following error: HARD ACL2 ERROR in F:  F got bad input 3.

  NIL
  ?
 })

 <p>Note that when a raw Lisp error occurs because @('*hard-error-is-error*')
 is non-@('nil'), the error message will not use @(see iprinting).  The reason
 is that the implementation does not make values of iprint indices available
 after the message is printed; so it would be misleading or an error to read
 @('#@i#') after that return.</p>

 @(def hard-error)")

(defxdoc header
  :parents (arrays acl2-built-ins)
  :short "Return the header of a 1- or 2-dimensional array"
  :long "@({
  Example Form:
  (header 'delta1 a)

  General Form:
  (header name alist)
 })

 <p>where @('name') is arbitrary and @('alist') is a 1- or 2-dimensional array.
 This function returns the header of the array @('alist').  The function
 operates in virtually constant time if @('alist') is the semantic value of
 @('name').  See @(see arrays).</p>

 @(def header)")

(defxdoc heavy-linear-p
  :parents (linear-arithmetic system-attachments)
  :short "Extend the use of @(see linear-arithmetic) during rewriting"
  :long "<p>This topic concerns an advanced control for the ACL2 prover.</p>

 <p>This zero-ary attachable system function supports extending the usual use
 of @(see linear-arithmetic) during rewriting, specifically with the
 test (first) argument of a call of @('IF').  To get this additional power,
 possibly at considerable loss of efficiency, evaluate @('(defattach-system
 heavy-linear-p constant-t-function-arity-0)').  To restore the default
 behavior, evaluate @('(defattach-system heavy-linear-p
 constant-nil-function-arity-0)').</p>")

(defxdoc hidden-death-package
  :parents (packages defpkg)
  :short "Handling @(tsee defpkg) @(see events) that are @(tsee local)"
  :long "<p>This documentation topic explains a little bit about certain errors
 users may see when attempting to evaluate a @(tsee defpkg) event.  In brief,
 if you see an error that refers you to this topic, you are probably trying to
 admit a @(tsee defpkg) event, and you should change the name of the package to
 be introduced by that event.</p>

 <p>Recall that @('defpkg') events introduce axioms, for example as
 follows.</p>

 @({
  ACL2 !>(defpkg "PKG0" '(a b))

  Summary
  Form:  ( DEFPKG "PKG0" ...)
  Rules: NIL
  Warnings:  None
  Time:  0.01 seconds (prove: 0.00, print: 0.00, other: 0.01)
   "PKG0"
  ACL2 !>:pr! "PKG0"

  Rune:         (:REWRITE PKG0-PACKAGE)
  Enabled:      T
  Hyps:         T
  Equiv:        EQUAL
  Lhs:          (PKG-IMPORTS "PKG0")
  Rhs:          '(A B)
  Backchain-limit-lst: NIL
  Subclass:     ABBREVIATION
  ACL2 !>
 })

 <p>Consider a @(tsee defpkg) event that is introduced during evaluation of an
 @(tsee include-book) event, where that @('include-book') event occurs @(see
 local)ly inside a surrounding @(tsee encapsulate) event or another
 @('include-book') event.  In that case, traces of the axiom added by the
 @('defpkg') event will disappear after the surrounding event is admitted.  If
 ACL2 were to allow the same package name to be defined subsequently with a
 different set of imports, that could cause inconsistencies.  See @(see
 package-reincarnation-import-restrictions) for relevant discussion, or see the
 &ldquo;Essay on Hidden Packages&rdquo; in source file @('axioms.lisp')..</p>

 <p>In order to prevent unsoundness, ACL2 maintains the following invariant.
 Let us say that a @('defpkg') event is ``hidden'' if it is in support of the
 current logical @(see world) but is not present in that world as an event,
 because it is @(tsee local) as indicated above.  We maintain the invariant
 that all @(tsee defpkg) @(see events), even if ``hidden'', are tracked
 under-the-hood in the current logical @(see world).  Sometimes this property
 causes @(tsee defpkg) events to be written to the @(see portcullis) of a
 book's @(see certificate) (see @(see books)).  This invariant guarantees that
 if you then try to define a package in a manner inconsistent with its earlier
 definition &mdash; specifically, with a different imports list &mdash; you
 will see an error because of the tracking discussed above.</p>

 <p>(By the way, this topic's name comes from Holly Bell, who heard "hidden
 death package" instead of "hidden defpkg".  The description seemed to fit.
 Thanks, Holly!)</p>")

(defxdoc hidden-defpkg
  :parents (packages defpkg)
  :short "Handling defpkg events that are local"
  :long "<p>See @(see hidden-death-package)</p>")

(defxdoc hide
  :parents (rewrite)
  :short "Hide a term from the rewriter"
  :long "<p>@('Hide') is actually the @(see identity) function: @('(hide x) =
 x') for all @('x').  However, terms of the form @('(hide x)') are ignored by
 the ACL2 rewriter, except when explicit @(':expand') @(see hints) are given
 for such terms (see @(see hints)) or when rewrite rules explicitly about
 @('hide') are available.  An @(':expand') hint that removes all calls of
 @('hide') is:</p>

 @({
  :expand ((:free (x) (hide x)))
 })

 <p>The above hint can be particularly useful when ACL2's equality heuristics
 apply @('hide') to an equality after substituting it into the rest of the
 goal, if that goal (or a subgoal of it) fails to be proved.</p>

 <p>Another common case, described below, is when @('hide') is added by the
 simplifier because an attempted execution of the term failed.  In this case,
 an @(':expand') hint as described above will have no effect because the
 execution will just fail again; the @('hide') will be re-inserted; and the
 hapless user will find themselves questioning their own sanity.</p>

 <p>@('Hide') terms are generally ignored not only by the rewriter but by other
 ACL2 procedures, including the induction heuristics and (by default) removal
 of @(see guard-holders).</p>

 <p>Sometimes the ACL2 simplifier inserts @('hide') terms into a proof attempt
 out of the blue, as it were.  Why and what can you do about it?  Suppose you
 have a constrained function, say @('constrained-fn'), and you define another
 function, say @('another-fn'), in terms of it, as in:</p>

 @({
  (defun another-fn (x y z)
    (if (big-hairy-test x y z)
        (constrained-fn x y z)
        t))
 })

 <p>Suppose the term @('(another-fn 1 2 3)') arises in a proof.  Since the
 arguments are all constants, ACL2 may try to reduce such a term to a constant
 by executing the definition of @('another-fn').  However, after a possibly
 extensive computation (because of @('big-hairy-test')) the execution fails
 because of the unevaluable call of @('constrained-fn').  To avoid subsequent
 attempts to evaluate the term, ACL2 embeds it in a @('hide') expression.
 Often that expression will use a call of @(tsee comment), where @('(comment x
 y)') is logically just @('y'), to tell you the problematic constrained
 function, in this case by rewriting the original expression to the following;
 see @(see comment).  (Near the end of this topic we discuss how to avoid the
 call of @('comment').)</p>

 @({
 (hide (comment "Failed attempt to call constrained function CONSTRAINED-FN"
                (another-fn 1 2 3)))
 })

 <p>You might think this rarely occurs since all the arguments of
 @('another-fn') must be constants.  You would be right except for one special
 case: if @('another-fn') takes no arguments, i.e., is a constant function,
 then every call of it fits this case.  Thus, if you define a function @('f')
 of no arguments in terms of a constrained function @('g'), you may
 often see @('(f)') rewrite to:</p>

 @({
 (hide (comment "Failed attempt to call constrained function G"
                (f))).
 })

 <p>We do not hide the term if the @(see executable-counterpart) of the
 function is @(see disable)d &mdash; because we do not try to evaluate it in
 the first place.  Thus, to prevent the insertion of a @('hide') term into the
 proof attempt, you can globally disable the executable-counterpart of the
 offending defined function, e.g.,</p>

 @({
  (in-theory (disable (:executable-counterpart another-fn))).
 })

 <p>It is conceivable that you cannot afford to do this: perhaps some calls of
 the offending function must be computed while others cannot be.  One way to
 handle this situation is to leave the executable-counterpart enabled, so that
 @('hide') terms are introduced on the calls that cannot be computed, but prove
 explicit @(':')@(tsee rewrite) rules for each of those @('hide') terms.  For
 example, suppose that in the proof of some theorem, thm, it is necessary to
 leave the executable-counterpart of @('another-fn') enabled but that the call
 @('(another-fn 1 2 3)') arises in the proof and cannot be computed.  Thus the
 proof attempt will introduce the term @('(hide (comment ".." (another-fn 1 2
 3)))') mentioned above.  Suppose that you can show that @('(another-fn 1 2
 3)') is @('(constrained-fn 1 2 3)') and that such a step is necessary to the
 proof.  Unfortunately, proving the rewrite rule</p>

 @({
  (defthm thm-helper
    (equal (another-fn 1 2 3) (constrained-fn 1 2 3)))
 })

 <p>would not help the proof of thm because the target term is hidden inside
 the @('hide').  However,</p>

 @({
  (defthm thm-helper
    (equal (hide (comment "Failed attempt to call constrained function CONSTRAINED-FN"
                          (another-fn 1 2 3)))
           (constrained-fn 1 2 3)))
 })

 <p>would be applied in the proof of thm and is the rule you should prove.</p>

 <p>Now to prove @('thm-helper') you need to use the two ``tricks'' which have
 already been discussed.  First, to eliminate the @('hide') term in the proof
 of @('thm-helper') you should include a hint to @(':expand') that term.
 Second, to prevent the @('hide') term from being reintroduced when the system
 tries and fails to evaluate @('(another-fn 1 2 3)') you should include the
 hint @(':in-theory') @('(disable (:executable-counterpart another-fn))').
 Thus, @('thm-helper') will actually be:</p>

 @({
  (defthm thm-helper
    (equal (hide (comment "Failed attempt to call constrained function CONSTRAINED-FN"
                          (another-fn 1 2 3)))
           (constrained-fn 1 2 3))
    :hints
    (("Goal" :expand
             (hide (comment "Failed attempt to call constrained function CONSTRAINED-FN"
                            (another-fn 1 2 3)))
             :in-theory (disable (:executable-counterpart another-fn)))))
 })

 <p>See @(see eviscerate-hide-terms) for how to affect the printing of
 @('hide') terms.</p>

 <p>Finally, note that you can avoid the generation of @(tsee comment) calls
 inside the generated call of @('hide'), as was the case through ACL2 Version
 8.2, as follows.</p>

 @({
 (defattach-system ; generates (local (defattach ...))
   hide-with-comment-p
   constant-nil-function-arity-0)
 })

 <p>After evaluation of this event, our running example @('(another-fn 1 2 3)')
 would generate @('(hide (another-fn 1 2 3))') rather than a term of the
 form @('(hide (comment "..." (another-fn 1 2 3)))').</p>

 <p>In some cases such backward compatibility might also be achieved as
 follows; also see @(see guard-holders).</p>

 @({
 (defattach-system ; generates (local (defattach ...))
   remove-guard-holders-blocked-by-hide-p
   constant-nil-function-arity-0)
 })

 @(def hide)")

(defxdoc hints
  :parents (miscellaneous)
  :short "Advice to the theorem proving process"
  :long "<code>
 Examples:
 The following :hints value is nonsensical.  Nevertheless, it
 illustrates all of the available hint keywords except the
 ``custom keywords'' (see @(see custom-keyword-hints)) definable
 by the user.

 :hints (("Goal"
          :do-not-induct t
          :do-not '(generalize fertilize)
          :expand ((assoc x a)
                   :lambdas
                   (:free (y) (:with member (member y z))))
          :restrict ((&lt;-trans ((x x) (y (foo x)))))
          :hands-off (length binary-append)
          :in-theory (set-difference-theories
                       (current-theory :here)
                       '(assoc))
          :induct (list (nth n a) (nth n b))
          :use ((:instance assoc-of-append
                           (x a) (y b) (z c))
                (:functional-instance
                  (:instance p-f (x a) (y b))
                  (p consp)
                  (f assoc)))
          :bdd (:vars (c a0 b0 a1 b1) :prove nil :bdd-constructors (cons))
          :clause-processor (:function cl-proc :hint (my-hint clause))
          :instructions (:x :prove)
          :cases ((true-listp a) (consp a))
          :by (:instance rev-rev (x (cdr z)))
          :nonlinearp t
          :backchain-limit-rw 3
          :reorder (4 7 2)
          :case-split-limitations (20 10)
          :no-op t
          :no-thanks t
          :error ("Bad value ~x0." 123)
          :or (hint-kwd-alist-1 ... hint-kwd-alist-k)
          :rw-cache-state nil
          :backtrack (my-computed-hint clause processor clause-list)))
 </code>

 <p>Many of these hints affect the how the prover operates not only on the goal
 to which they are applied but also on its subgoals (and its subgoals'
 subgoals, etc.; for a deeper explanation see @(see hints-and-the-waterfall)).
 The following hints, however, have a specific effect only on the goal to which
 they are applied: @(':bdd'), @(':by'), @(':cases'), @(':clause-processor'),
 @(':error'), @(':induct'), @(':or'), and @(':use').  For example, suppose that
 you specify both a @(':cases') hint and an @(':expand') hint for
 @('"Goal"').  Then the @(':cases') hint will immediately result in subgoals,
 without calling the ACL2 rewriter; the @(':expand') hint will be used by the
 rewriter in subsequent goals.</p>

 <p>A very common hint is the @(':use') hint, which is described below.  In
 general it takes as its value a list of ``lemma instances'' (see @(see
 lemma-instance)), but it allows special cases, including a single lemma name.
 In each case, a goal @('G') is replaced by a new goal @('(IMPLIES P G)'),
 where @('P') is the theorem specified by the (conjunction of the) lemma
 instances provided.  Here are some examples.</p>

 @({
  ; Attach :use hint to the top-level goal G, which is named "Goal",
  ; replacing it by (implies P G) where P is the statement of lemma23:
  :hints (("Goal" :use lemma23))

  ; Equivalent to the above, using the trivial instance (i.e., with the empty
  ; substitution) of lemma23:
  :hints (("Goal" :use ((:instance lemma23))))

  ; Attach :use hint to the named subgoal, where the indicated lemma is used
  ; with the substitution that maps x to 17 and y to (foo z):
  :hints (("[1]Subgoal *1/1.2'" :use ((:instance lemma23
                                                   (x 17)
                                                   (y (foo z))))))

  ; Equivalent to the above: ACL2 allows you to omit the outer parentheses if
  ; there is only one lemma used.
  :hints (("[1]Subgoal *1/1.2'" :use (:instance lemma23
                                                  (x 17)
                                                  (y (foo z)))))
 })

 <p>ACL2 also provides ``custom keyword'' hints (see @(see
 custom-keyword-hints)) and even more general ``computed hints'' for the
 advanced user (see @(see computed-hints)).  Not documented in this topic are
 such hints implemented in books; for an example of so-called @(':consider')
 hints, see @(see consideration).</p>

 <p>When the ACL2 prover encounters a goal @('"G"'), then the first hint of
 the form @('("G" :kwd1 val1 ...)') is applied to that goal.  This usually
 means that all hints for the goal @('"G"') after the first such hint are
 ignored, and ACL2 produces a warning about that.  (Note however that
 @('("G")') is simply dropped; such an empty hint is considered not to be
 there, for purposes of this discussion.)  If there are default hints (see
 @(see set-default-hints)) then this behavior applies to the user-supplied list
 of @(':hints') followed by the default hints; see @(see
 hints-and-the-waterfall) for a detailed discussion of how hints fit into the
 ACL2 waterfall, which in particular has a &ldquo;slightly tricky
 example&rdquo; illustrating the unusual case when a goal can be encountered
 more than once, thus applying more than one hint on that goal.  Also see @(see
 override-hints) for an advanced feature that can modify the &ldquo;first
 hint&rdquo; behavior described above.  For examples of the sophisticated use
 of hints, primarily for experts, see community book
 @('books/hints/basic-tests.lisp').</p>

 <p>Duplicate hint keywords are prohibited in a hint; for example, the hint
 @('("Goal" :induct t :induct t)') is illegal.  Also, certain hint keywords
 are incompatible within a given hint, for example, in @('("Goal" :use
 nth :induct t)').  These restrictions for duplicates and compatibility apply
 not only for explicit hints but also for hints that are generated by computed
 hints or @(see override-hints); for example, the command
 @('(add-override-hints '((append '(:use nth :induct t) keyword-alist)))') will
 cause subsequent proof attempts to fail because @(':use') and @(':induct') are
 incompatible keywords.  Here is the full list of incompatibilities for hint
 keywords on a given goal.</p>

 <ul>

 <li>It is illegal to use two or more keywords from the following list, except
 that @(':use') and @(':cases') may be used together:<br/>
 @(`(cons :induct *top-hint-keywords*)`).</li>

 <li>It is illegal to use @(':reorder') with either @(':or') or
 @(':induct').</li>

 </ul>

 <p>Background: @('Hints') are allowed in all @(see events) that use the
 theorem prover.  During @(tsee defun) @(see events) there are two different
 uses of the theorem prover: one to prove termination and another to verify the
 @(see guard)s.  To pass a hint to the theorem prover during termination
 proofs, use the @(':hints') keyword in the @(tsee defun)'s @(tsee xargs)
 declaration.  To pass a hint to the theorem prover during the @(see guard)
 verification portion of admitting a @(tsee defun), use the @(':guard-hints')
 keyword in the @(tsee defun)'s @(tsee xargs) declaration.  The @(tsee
 verify-guards) event and the @(tsee defthm) event also use the theorem prover.
 To pass hints to them, use the @(':hints') keyword argument to the event.</p>

 @({
  General Form of Common :hints:
    ((goal-spec :key1 val1 ... :keyn valn)
     ...
     (goal-spec :key1 val1 ... :keyn valn))
 })

 <p>where @(tsee goal-spec) is as described elsewhere (see @(see goal-spec))
 and the keys and their respective values are shown below with their
 interpretations.  We also provide ``computed hints'' but discuss them
 separately; see @(see computed-hints).  The hint keywords below are considered
 in alphabetical order.</p>

 <dl>

 <dt>@(':backchain-limit-rw')</dt><p/>

 <dd><p>@('Value') is a natural number or @('nil'), indicating the level of
 backchaining for @(see rewrite), @(see meta), and @(see linear) rules.  This
 overrides, for the current goal and (as with @(':')@(tsee in-theory) hints)
 descendant goals, the default @(see backchain-limit)
 (see @(see set-backchain-limit)).</p></dd>

 <dt>@(':backtrack')</dt><p/>

 <dd><p>This is an advanced hint.  You can probably accomplish its effect by
 the use of ordinary computed hints; see @(see computed-hints).  But if you are
 an expert, read on.  (See @(see hints-and-the-waterfall) for some relevant
 background.)</p>

 <p>@('Value') is a computed hint, which is an expression that evaluates either
 to @('nil') &mdash; indicating that the @(':backtrack') hint is to have no
 effect &mdash; or to a non-empty alternating list of @(':keyi vali') pairs,
 as expected for a hint.  However, unlike ordinary computed hints,
 @(':backtrack') hints are evaluated <b>after</b> a goal has been processed to
 yield zero or more subgoals, not before.  Moreover, variables @('PROCESSOR')
 and @('CLAUSE-LIST') are allowed, but variable
 @('STABLE-UNDER-SIMPLIFICATIONP') is not.  We explain in more detail below,
 but first consider the following simple example.  First we define a standard
 list reversal function:</p>

 @({
  (defun rev (x)
    (if (consp x)
        (append (rev (cdr x)) (cons (car x) nil))
      nil))
 })

 <p>Now we prove:</p>

 @({
  (thm (true-listp (rev x)))
 })

 <p>The successful proof includes the following output.</p>

 @({
  Subgoal *1/1'
  (IMPLIES
    (AND (CONSP X)
         (TRUE-LISTP (REV (CDR X))))
    (TRUE-LISTP (APPEND (REV (CDR X)) (LIST (CAR X))))).

  The destructor terms (CAR X) and (CDR X) can be
  eliminated by using CAR-CDR-ELIM to replace X
  by (CONS X1 X2), (CAR X) by X1 and (CDR X) by
  X2.  This produces the following goal.

  Subgoal *1/1''
  (IMPLIES (AND (CONSP (CONS X1 X2))
                (TRUE-LISTP (REV X2)))
           (TRUE-LISTP (APPEND (REV X2) (LIST X1)))).
 })

 <p>But suppose that we attach a @(':backtrack') hint to the goal above at
 which destructor elimination was applied:</p>

 @({
  (thm (true-listp (rev x))
       :hints (("Subgoal *1/1'"
                :backtrack
                (quote (:do-not '(eliminate-destructors))))))
 })

 <p>Then when ACL2 applies destructor elimination as displayed above, this time
 the @(':backtrack') hint applies, evaluating to @('(:do-not
 '(eliminate-destructors))').  Since this list is not @('nil'), the prover
 decides not to keep the new subgoal, and instead supplies this @(':do-not')
 hint before attacking the goal again.  In this example, ACL2 happens to use a
 technique later in its ``waterfall'' arsenal than destructor elimination,
 namely, generalization:</p>

 @({
  Subgoal *1/1'
  (IMPLIES
    (AND (CONSP X)
         (TRUE-LISTP (REV (CDR X))))
    (TRUE-LISTP (APPEND (REV (CDR X)) (LIST (CAR X))))).

  [Note:  A hint was supplied for the goal above,
  because of a :backtrack hint that is preventing
  destructor elimination. Thanks!]

  We generalize this conjecture, replacing
  (REV (CDR X)) by RV.  This produces

  Subgoal *1/1''
  (IMPLIES (AND (CONSP X) (TRUE-LISTP RV))
           (TRUE-LISTP (APPEND RV (LIST (CAR X))))).
 })

 <p>We now provide a careful explanation of how @(':backtrack') hints work, but
 we suggest that you keep the example above in mind.  If ``@(':backtrack
 form')'' is part of the hint that has been selected for a goal, then @('form')
 is evaluated when one of ACL2's @(see clause) processors successfully applies
 to the current goal to produce a list of subgoals.  This evaluation takes
 place in an environment just like that for any computed hint (see @(see
 computed-hints)), with the following exceptions.  First, the variable
 @('STABLE-UNDER-SIMPLIFICATIONP') is not allowed to occur free in @('form'),
 but instead the following new variables are allowed to occur free and are
 bound for this evaluation as follows: @('PROCESSOR') is bound to the processor
 in the list @('*preprocess-clause-ledge*') that has applied to the goal, and
 @('CLAUSE-LIST') is bound to the list of clauses (each a list of literals that
 is implicitly disjoined) returned by that clause processor.  Second, the
 variables @('HIST') and @('PSPV') are bound to the history and pspv returned
 by the clause processor, <b>not</b> the ones that were passed to the clause
 processor.  If this evaluation returns an error, then the proof aborts, as for
 any computed hint whose evaluation returns an error.  If this evaluation
 returns @('nil'), then the @(':backtrack') hint has no effect, and the goal is
 replaced by the list of goals (the value of @('CLAUSE-LIST') described above),
 as usual.  Otherwise, the clause processor is deemed to have failed, and the
 goal clause is tried again starting at the top of the waterfall after
 selecting the hint returned by the above evaluation.  That hint will normally
 be an alternating list of hint keywords and their values, but if it is a
 custom keyword hint (see @(see custom-keyword-hints)), then it will be handled
 in the usual manner but with the first three variables above bound to the
 symbol @(':OMITTED').  Of course, if the new hint includes a value for
 @(':BACKTRACK') then this process can loop; care should be taken to keep that
 from happening.</p>

 <p>A final note about @(':BACKTRACK') hints: since these are a form of
 computed hints, @(see override-hints) (if any) are applied to their evaluation
 result just as with any computed hint.  That is, the backtrack hint is
 successively modified with each override-hint, to produce a final hint that is
 actually used (or, ignored if that final hint is @('nil')).  See @(see
 override-hints).</p></dd>

 <dt>@(':')@(tsee bdd)</dt><p/>

 <dd><p>This hint indicates that ACL2's built-in ordered binary decision
 diagrams (BDDs) with rewriting are to be used to prove or simplify the goal.
 See @(see bdd) for an introduction to the ACL2 BDD algorithm.</p>

 <p>@('Value') is a list of even length, such that every other element,
 starting with the first, is one of the keywords @(':vars'),
 @(':bdd-constructors'), @(':prove'), or @(':literal').  Each keyword that is
 supplied should be followed by a value of the appropriate form, as shown
 below; for others, a default is used.  Although @(':vars') must always be
 supplied, we expect that most users will be content with the defaults used for
 the other values.</p>

 <blockquote>

 <p>@(':vars') &mdash; A list of ACL2 variables, which are to be treated as
 Boolean variables.  The prover must be able to check, using @(see
 type-reasoning), that each of these variables is Boolean in the context of the
 current goal.  Note that the prover will use very simple heuristics to order
 any variables that do not occur in @(':vars') (so that they are ``greater
 than'' the variables that do occur in @(':vars')), and these heuristics are
 often far from optimal.  In addition, any variables not listed may fail to be
 assumed Boolean by the prover, which is likely to seriously impede the
 effectiveness of ACL2's BDD algorithm.  Thus, users are encouraged <i>not</i>
 to rely on the default order, but to supply a list of variables instead.
 Finally, it is allowed to use a value of @('t') for @('vars').  This means the
 same as a @('nil') value, except that the BDD algorithm is directed to fail
 unless it can guarantee that all variables in the input term are known to be
 Boolean (in a sense discussed elsewhere; see @(see bdd-algorithm)).</p>

 <p>@(':literal') &mdash; An indication of which part of the current goal
 should receive BDD processing.  Possible values are:</p>

 @({
    :all     treat entire goal as a single literal (the default)
    :conc    process the conclusion
    n        process the hypothesis with index n (1, 2, ...)
 })

 <p>@(':bdd-constructors') &mdash; When supplied, this value should be a list
 of function symbols in the current ACL2 @(see world); it is @('(cons)') by
 default, unless @(':bdd-constructors') has a value in the @(tsee
 acl2-defaults-table) by default, in which case that value is the default.  We
 expect that most users will be content with the default.  See @(see
 bdd-algorithm) for information about how this value is used.</p>

 <p>@(':prove') &mdash; When supplied, this value should be @('t') or @('nil');
 it is @('t') by default.  When the goal is not proved and this value is
 @('t'), the entire proof will abort.  Use the value @('nil') if you are happy
 to the proof to go on with the simplified term.</p>

 </blockquote></dd>

 <dt>@(':by')</dt><p/>

 <dd><p>@('Value') is a @(see lemma-instance), @('nil'), or a new event
 name. If the value is a @(see lemma-instance) (see @(see lemma-instance)),
 then it indicates that the goal (when viewed as a clause) is either equal to
 the proposition denoted by the instance, or is subsumed by that proposition
 when both are viewed as clauses.  To view a formula as a clause, union
 together the negations of the hypotheses and add the conclusion.  For
 example,</p>

 @({
  (IMPLIES (AND (h1 t1) (h2 t2)) (c t1))
 })

 <p>may be viewed as the clause</p>

 @({
  {~(h1 t1) ~(h2 t2) (c t1)}.
 })

 <p>Clause @('c1') is ``subsumed'' by clause @('c2') iff some instance of
 @('c2') is a subset of @('c1').  For example, the clause above is subsumed by
 @('{~(h1 x) (c x)}'), which when viewed as a formula is @('(implies (h1 x) (c
 x))').</p>

 <p>Note that if the value is the name of a function symbol introduced by
 @(tsee defun), then the original form of the body of that definition is used.
 This behavior differs from that provided by a @(':use') hint, which uses the
 normalized (simplified) body; see @(see normalize).</p>

 <p>If the value is @('nil') or a new name, the prover does not even attempt to
 prove the goal to which this hint is attached.  Instead the goal is given a
 ``bye'', i.e., it is skipped and the proof attempt continues as though the
 goal had been proved.  If the prover terminates without error then it reports
 that the proof would have succeeded had the indicated goals been proved and it
 prints an appropriate @(see defthm) form to define each of the @(':by') names.
 The ``name'' @('nil') means ``make up a name.''  Here is an example
 (admittedly contrived for illustration purposes).</p>

 @({
  ACL2 !>(thm (equal (append (append x y) z)
                     (append x y z))
              :hints (("Subgoal *1/2'" :by nil)))

  Name the formula above *1.

  [[... output omitted here ...]]

  [Note:  A hint was supplied for the goal below.  Thanks!]

  Subgoal *1/2'
  (IMPLIES (AND (CONSP X)
                (EQUAL (APPEND (APPEND (CDR X) Y) Z)
                       (APPEND (CDR X) Y Z)))
           (EQUAL (APPEND (APPEND X Y) Z)
                  (APPEND X Y Z))).

  But we have been asked to pretend that this goal is subsumed by the
  yet-to-be-proved |THM Subgoal *1/2'|.

  Subgoal *1/1
  [[... proof goes on; further output omitted here ...]]
 })

 <p>The system does not attempt to check the uniqueness of the @(':by') names
 (supplied or made up), since by the time those goals are proved the namespace
 will be cluttered still further.  Therefore, the final list of ``appropriate''
 @(tsee defthm) forms may be impossible to admit without some renaming by the
 user.  If you must invent new names, remember to substitute the new ones for
 the old ones in the @(':by') hints themselves.</p></dd>

 <dt>@(':')@(tsee case-split-limitations)</dt><p/>

 <dd><p>@('Value') is the same as for @(tsee set-case-split-limitations).  The
 simplifier will behave as though the value had instead been supplied to
 @('set-case-split-limitations'); see @(see set-case-split-limitations).  This
 behavior will persist through subgoals unless overridden by another
 @(':CASE-SPLIT-LIMITATIONS') hint.</p></dd>

 <dt>@(':cases')</dt><p/>

 <dd><p>@('Value') is a non-empty list of terms.  For each term in the list, a
 new goal is created from the current goal by assuming that term; and also, in
 essence, one additional new goal is created by assuming all the terms in the
 list false.  We say ``in essence'' because if the disjunction of the terms
 supplied is a tautology, then that final goal will be a tautology and hence
 will in fact never actually be created.</p></dd>

 <dt>@(':')@(tsee clause-processor)</dt><p/>

 <dd><p>@('Value') specifies the application of a user-defined simplifier to
 the current goal.  See @(see clause-processor), which provides necessary
 background and hint syntax.  Also see @(see define-trusted-clause-processor)
 for a discussion of ``trusted clause-processors'': goal-level simplifiers that
 may be external to ACL2 and do not need to be proved correct in ACL2.</p>

 <p>You can see all current @(':clause-processor') rules by issuing the command
 @('(print-clause-processor-rules)'), and you can see the names of all trusted
 clause-processors by issuing the command @('(table
 trusted-cl-proc-table)').</p></dd>

 <dt>@(':do-not')</dt><p/>

 <dd><p>@('Value') is a term having at most the single free variable @(tsee
 world), which when evaluated (with @(tsee world) bound to the current ACL2
 logical @(see world)) produces a list of symbols that is a subset of the
 list</p>

 @({
  (preprocess ;propositional logic, simple rules
   simplify   ;as above plus rewriting, linear arithmetic
   eliminate-destructors
   fertilize  ;use of equalities
   generalize
   eliminate-irrelevance).
 })

 <p>The hint indicates that the ``processes'' named should not be used at or
 below the goal in question.  Thus, to prevent generalization and
 fertilization, say, include the hint</p>

 @({
  :do-not '(generalize fertilize)
 })

 <p>If @('value') is a single symbol, as in</p>

 @({
  :do-not generalize,
 })

 <p>it is taken to be @(''(value)').</p>

 <p>See also @(see do-not-hint) for a way to automatically provide
 @(':do-not') hints across several theorems.</p></dd>

 <dt>@(':do-not-induct')</dt><p/>

 <dd><p>@('Value') indicates whether @(see induction) is permitted under the
 specified goal.  The legal values are @('t'), @(':otf-flg-override'),
 @(':otf'), @('nil'), or a non-keyword symbol other than @('t') or @('nil').
 The default is @('nil'), meaning that induction is permitted as usual.  A
 non-@('nil') value prohibits the use of induction to prove the indicated goal
 or any of its subgoals, as described below.</p>

 <p>If @('value') is @('t') or @(':otf-flg-override'), then the attempt to
 apply @(see induction) to the indicated goal or any subgoal under the
 indicated goal will immediately cause the theorem prover to report @(see
 failure), except that if @(':otf-flg t') is specified (see @(see otf-flg)) and
 @('value') is @('t'), then the proof will continue until the time at which the
 goal pushed for induction is finally encountered and causes failure.  The
 latter behavior is also what occurs if @('value') is @(':otf').  See however
 the @(':induct') hint below.  If @('value') is a non-keyword symbol other than
 @('t') or @('nil'), the theorem prover will skip every subgoal under the
 indicated goal (giving it a ``bye'', as with a ``@(':by')'' hint) that would
 otherwise be attacked with induction.  This will cause the theorem prover to
 fail eventually, printing every subgoal thus skipped in the form of an event
 to prove, each with a name based on the value of the @(':do-not-induct') hint
 that caused that subgoal to be skipped.</p>

 <p><b>Remarks.</b></p>

 <p>(1) An @(':induct') hint is applied to a goal even if a @(':do-not-induct')
 hint is in effect for that goal.  Consider the following examples.</p>

 @({
 (thm (equal (append (append x y) z) (append x y z))
      :hints (("Goal" :induct t :do-not-induct t)))

 (thm (and (equal (append (append x y) z) (append x y z))
           (equal (append (append u v) w) (append u v w)))
      :hints (("Goal" :do-not-induct t)
              ("Subgoal 2" :induct t)))
 })

 <p>In the first of these, the @(':do-not-induct') hint has no effect on the
 proof; instead, the @(':induct') hint forces an induction that allows the
 proof to succeed (without any sub-inductions).  The second of these
 illustrates that even though @(':do-not-induct') can stop sub-inductions, its
 effect is overridden by @(':induct').  For the proof of that second example,
 ACL2 immediately splits into two subgoals.  Then in spite of the top-level
 @(':do-not-induct') hint, the proof is allowed to proceed past Subgoal 2,
 which requires induction, because of the hint @(':induct t').  However, the
 proof halts after Subgoal 1 because of the @(':do-not-induct') hint that has
 been established ``above'' it, at @('"Goal"').  (For more about the way
 hints are processed, see @(see hints-and-the-waterfall).)</p>

 <p>(2) For an advanced example of the use of value @(':otf') for
 @(':do-not-induct') combined with @(see override-hints), see community book
 @('books/hints/basic-tests.lisp').</p></dd>

 <dt>@(':error')</dt><p/>

 <dd><p>@('Value') is typically a ``fmt message'' to be printed by the @(tsee
 fmt) tilde-directive ~@@ but may be any object.  The effect of this hint is to
 cause an error when the hint is translated.  There is no reason to include an
 @(':ERROR') hint in any user-typein, since it will only cause an error when
 the form is evaluated.  @(':ERROR') hints are useful in the definition of
 functions that generate custom keyword hints (see @(see custom-keyword-hints))
 and computed hints (see @(see computed-hints)).  For example, if you wish to
 define a custom keyword hint @(':my-hint val') and you wish the hint to signal
 an error if there is something inappropriate about @('val') in the context of
 the hint, use the following code to generate the hint</p>

 @({
  (list :ERROR (cons "Your specified value, ~x0, is inappropriate"
                     (list (cons #0 val))))
 })

 <p>which is equivalent to</p>

 @({
  (list :ERROR (msg "Your specified value, ~x0, is inappropriate"
                    val))
 })

 <p>which, if @('val') has the value @('123'), would evaluate to the hint</p>

 @({
  (:ERROR ("Your specified value, ~x0, is inappropriate" (#0 . 123))).
 })

 <p>Note that any time an @(':ERROR') keyword is produced during hint
 processing, including iterations of the expansions of custom keyword hints or
 of @(see override-hints), an error will occur.</p></dd>

 <dt>@(':expand')</dt><p/>

 <dd><p>@('Value') is a true list of terms, each of which is of one of the
 forms @('(let ((v1 t1)...) b)') or @('(fn t1 ... tn)'), where @('fn') is a
 defined function symbol with formals @('v1, ..., vn,') and @('body') @('b').
 Such a term is said to be ``expandable:'' it can be replaced by the result of
 substituting the @('ti')'s for the @('vi')'s in @('b').  The terms listed in
 the @(':expand') hint are expanded when they are encountered by the simplifier
 while working on the specified goal or any of its subgoals.  (There is no
 separate ``expand'' process.)  We permit @('value') to be a single such term
 instead of a singleton list.  <b>Remarks</b>: (0) Note that in the event that
 a @(':definition') rule has been admitted for @('fn'), then by default, the
 body @('b') is determined by the (most recently admitted such) rule rather
 than the original definition of @('fn'); see @(see definition).  (1) Allowed
 are ``terms'' of the form @('(:free (var1 var2 ...  varn) pattern)') where the
 indicated variables are distinct and @('pattern') is a term.  Such ``terms''
 indicate that we consider the indicated variables to be instantiatable, in the
 following sense: whenever the simplifier encounters a term that can be
 obtained from @('pattern') by instantiating the variables @('(var1 var2 ...
 varn)'), then it expands that term.  (2) Also allowed are ``terms'' of the
 form @('(:with name term)'), where @('name') is a function symbol, a macro
 name that denotes a function symbol (see @(see macro-aliases-table)), or a
 @(see rune).  The corresponding @(see definition) rule or (less often) @(tsee
 rewrite) rule is then used in place of the current body for the function
 symbol of @('term'); see @(see show-bodies) and see @(see set-body).  If the
 rule is of the form @('(implies hyp (equiv lhs rhs))'), then after matching
 @('lhs') to the current term in a context that is maintaining equivalence
 relation @('equiv'), ACL2 will replace the current term with @('(if hyp rhs
 (hide term))'), or just @('rhs') if the rule is just @('(equal lhs rhs)').
 (3) A combination of both @(':free') and @(':with'), as described above, is
 legal.  (4) The term @(':LAMBDAS') is treated specially.  It denotes the list
 of all lambda applications (i.e., @(tsee let) expressions) encountered during
 the proof.  Conceptually, this use of @(':LAMBDAS') tells ACL2 to treat lambda
 applications as a notation for substitutions, rather than as function calls
 whose opening is subject to the ACL2 rewriter's heuristics (specifically, not
 allowing lambda applications to open when they introduce ``too many'' if
 terms).</p></dd>

 <dt>@(':hands-off')</dt><p/>

 <dd><p>@('Value') is a true list of function symbols or lambda expressions,
 indicating that under the specified goal applications of these functions are
 not to be rewritten.  Note however that subterms will still be rewritten; see
 @(see hide) if that is not what is intended.  (The community book
 @('books/clause-processors/autohide.lisp') from Jared Davis may also be
 helpful in that case.) @('Value') may also be a single function symbol or
 lambda expression instead of a list.</p></dd>

 <dt>@(':')@(tsee in-theory)</dt><p/>

 <dd><p>@('Value') is a ``theory expression,'' i.e., a term having at most the
 single free variable @(tsee world) which when evaluated (with @(tsee world)
 bound to the current ACL2 logical world (see @(see world))) will produce a
 theory to use as the current theory for the goal specified.  See @(see
 theories).</p>

 <p>Note that an @(':')@(tsee IN-THEORY) hint will always be evaluated relative
 to the current ACL2 logical @(see world), not relative to the theory of a
 previous goal.  Consider the following example.</p>

 @({
  (defthm prop
    (p (f (g x)))
    :hints (("Goal"      :in-theory (disable f))
            ("Subgoal 3" :in-theory (enable  g))))
 })

 <p>Consider in particular the theory in effect at @('Subgoal 3').  This call
 of the @(tsee enable) macro enables @('g') relative to the @(tsee
 current-theory) of the current logical @(see world), <i>not</i> relative to
 the theory produced by the hint at @('Goal').  Thus, the @(tsee disable) of
 @('f') on behalf of the hint at @('Goal') will be lost at @('Subgoal 3'), and
 @('f') will be enabled at @('Subgoal 3') if was enabled globally when
 @('prop') was submitted.</p></dd>

 <dt>@(':induct')</dt><p/>

 <dd><p>@('Value') is either @('t') or a term that is not an atom or a quoted
 constant.  The value @('t') indicates that the system use induction
 immediately by applying its induction heuristic to the specified goal
 (without trying simplification, etc.).  Otherwise, the system should apply
 induction immediately, but it should analyze @('value') rather than the goal
 to generate its @(see induction) scheme.  Either way (i.e., for value @('t')
 or not), merging and the other @(see induction) heuristics are applied.  Thus,
 if @('value') contains several mergeable @(see induction)s, the ``best'' will
 be created and chosen.  E.g., the @(':induct') hint</p>

 @({
   (list (nth i a) (nth j a))
 })

 <p>suggests simultaneous @(see induction) on @('i'), @('j'), and @('a').</p>

 <p>When the selected induction scheme is suggested by just one term the
 induction is announced with a message like ``@('We will induct according to a
 scheme suggested by')'' the term in question. But if several terms are
 involved in the suggestion, either because they suggested the same scheme or
 because their suggestions were merged with others to form the selected scheme,
 the announcement includes the phrase ``@('while accommodating')'' the other
 terms.  Furthermore, as noted in @(see induction-heuristics), the induction
 mechanism communicates to the simplifier, passing to it the list of all the
 terms being accommodated.  The simplifier preferentially expands those terms
 during the subsequent proof attempt.</p>

 <p>Thus, if the prover automatically selects an induction that accommodates
 terms besides the one suggesting and justifying the induction, and you want to
 give an @(':induct') hint that causes the same behavior, your hint should
 include the term suggesting the induction and all of the accommodated terms.
 We typically do this with a hint like @(':induct (list term0 term1
 ... termk)').</p>

 <p>If both an @(':induct') and a @(':do-not-induct') hint are supplied for a
 given goal then the indicated @(see induction) is applied to the goal and the
 @(':do-not-induct') hint is inherited by all subgoals generated.</p></dd>

 <dt>@(':')@(tsee instructions)</dt><p/>

 <dd><p>@('Value') is a list of interactive @(see proof-builder) instructions;
 see @(see instructions).  Unlike other hint keywords described here, this one
 is actually a custom keyword hint (see @(see custom-keyword-hints)) that
 generates a suitable @(':')@(tsee clause-processor) hint.</p></dd>

 <dt>@(':no-op')</dt><p/>

 <dd><p>@('Value') is any object and is irrelevant.  This hint has no effect,
 although unlike an empty hint such as @('("Goal")'), it is not dropped.
 Thus, @('("Goal" :no-op t)') will shadow any later (or default) hint on
 @('"Goal"'), but @('("Goal")') will not.  Unlike other hint keywords,
 multiple occurrences of the keyword @(':no-op') are tolerated.</p></dd>

 <dt>@(':no-thanks')</dt><p/>

 <dd><p>@('Value') is any object.  This hint does nothing, except that if
 @('value') is non-@('nil') then the usual ``[Note: A hint was
 supplied... Thanks!]'' is not printed.</p></dd>

 <dt>@(':nonlinearp')</dt><p/>

 <dd><p>@('Value') is @('t') or @('nil'), indicating whether @(see
 non-linear-arithmetic) is active.  The default value is @('nil').  See @(see
 non-linear-arithmetic).</p></dd>

 <dt>@(':or')</dt><p/>

 <dd><p>@('Value') is a list @('(kwd-val-listp-1 ... kwd-val-listp-k)'), where
 each @('kwd-val-listp-i') is a list satisfying @(tsee keyword-value-listp),
 i.e., an alternating list of keywords and values.  This hint causes an attempt
 to prove the specified goal using hints @('kwd-val-listp-i') in
 sequence (first @('kwd-val-listp-1'), then @('kwd-val-listp-2'), and so on),
 until the first of these succeeds.  If none succeeds, then the prover proceeds
 after heuristically choosing the ``best'' result, taking into account the
 goals pushed in each case for proof by induction.</p>

 <p>The following (contrived but illustrative example illustrates how @(':or')
 hints work.</p>

 @({
    ACL2 !>(thm (f x)
                :hints
                (("Goal"
                  :expand ((nth x 3))
                  :or ((:in-theory (disable car-cons))
                       (:use cdr-cons :in-theory (enable append)))
                  :do-not '(generalize))))

    [Note:  A hint was supplied for the goal above.  Thanks!]

    The :OR hint for Goal gives rise to two disjunctive branches.  Proving
    any one of these branches would suffice to prove Goal.  We explore
    them in turn, describing their derivations as we go.

    ---
    Subgoal D2
    ( same formula as Goal ).

    The first disjunctive branch (of 2) for Goal can be created by applying
    the hint:
    ("Subgoal D2" :EXPAND ((NTH X 3))
                  :IN-THEORY (DISABLE CAR-CONS)
                  :DO-NOT '(GENERALIZE)).

    [Note:  A hint was supplied for the goal above.  Thanks!]

    Normally we would attempt to prove this formula by induction.  However,
    we prefer in this instance to focus on the original input conjecture
    rather than this simplified special case.  We therefore abandon our
    previous work on this conjecture and reassign the name *1 to the original
    conjecture.  (See :DOC otf-flg.)  [Note:  Thanks again for the hint.]

    ---
    Subgoal D1
    ( same formula as Goal ).

    The second disjunctive branch (of 2) for Goal can be created by applying
    the hint:
    ("Subgoal D1" :EXPAND ((NTH X 3))
                  :USE CDR-CONS
                  :IN-THEORY (ENABLE APPEND)
                  :DO-NOT '(GENERALIZE)).

    [Note:  A hint was supplied for the goal above.  Thanks!]

    ACL2 Warning [Use] in ( THM ...):  It is unusual to :USE the formula
    of an enabled :REWRITE or :DEFINITION rule, so you may want to consider
    disabling (:REWRITE CDR-CONS) in the hint provided for Subgoal D1.
    See :DOC using-enabled-rules.

    We augment the goal with the hypothesis provided by the :USE hint.
    The hypothesis can be obtained from CDR-CONS.  We are left with the
    following subgoal.

    Subgoal D1'
    (IMPLIES (EQUAL (CDR (CONS X Y)) Y)
             (F X)).

    By the simple :rewrite rule CDR-CONS we reduce the conjecture to

    Subgoal D1''
    (F X).
 })

 <p>... and so on.  This example illustrates how ACL2 processes @(':or') hints
 in general.  For each @('i') from 1 to @('k'), a so-called ``disjunctive''
 subgoal is created by splicing @('kwd-val-listp-i') into the other hint values
 (if any) supplied for the given goal, in order.  A corresponding subgoal is
 created for each @('i'), numbered in the usual manner (hence, counting down)
 except that the ``@('D')'' is prefixed to each resulting goal.</p></dd>

 <dt>@(':reorder')</dt><p/>

 <dd><p>@('Value') is a list of positive integers without duplicates,
 corresponding to the numbering of subgoals generated for the @(see goal-spec)
 @('"G"'), say @('"G.k"') down to @('"G.1"').  Those subgoals are
 reordered so that if @('value') is @('(n1 n2 ... nk)'), then the goal now
 numbered @('"G.k"') will be the goal originally numbered @('"G.n1"'); the
 goal now numbered @('"G.k-1"') will be the goal formerly numbered
 @('"G.n2"'); and so on, down the list of @('ni'), after which the goals not
 yet printed are printed in their original order.  Note that reordering for
 subgoals of a goal to be proved by induction, such as @('*1'), is not
 supported.</p></dd>

 <dt>@(':restrict')</dt><p/>

 <dd><p>This hint, originally suggested by Bishop Brock, sometimes allows rules
 with free variables (see @(see free-variables)) to be applied successfully by
 the rewriter, thus avoiding the clutter, case-splitting, and theory management
 (disabling) that can occur with @(':use') hints.</p>

 <p>Warning: This is a sophisticated hint that may be most appropriate for
 experienced ACL2 users.  In particular, @(':restrict') hints are ignored by
 the preprocessor, so you might find it useful to give the hint @(':do-not
 '(preprocess)') when using any @(':restrict') hints, at least if the rules in
 question are abbreviations (see @(see simple)).</p>

 <p>@('Value') is an association list.  Its members are of the form @('(x
 subst_1 subst_2 ...)'), where: @('x') is either (1) a @(see rune) whose @(tsee
 car) is @(':')@(tsee rewrite) or @(':')@(tsee definition) or (2) an event name
 corresponding to one or more such @(see rune)s; and @('(subst_1 subst_2 ...)')
 is a non-empty list of substitutions, i.e., of association lists pairing
 variables with terms.  First consider the case that @('x') is a @(':')@(tsee
 rewrite) or @(':')@(tsee definition) @(see rune).  Recall that without this
 hint, the rule named @('x') is used by matching its left-hand side (call it
 @('lhs')) against the term currently being considered by the rewriter, that
 is, by attempting to find a <i>matching substitution</i>, @('s'), such that
 the instantiation of @('lhs') using @('s') is equal to that term.  If however
 the @(':restrict') hint contains @('(x subst_1 subst_2 ...)'), then this
 behavior will be modified by restricting @('s') so that it must extend
 @('subst_1'); and if there is no such @('s'), then @('s') is restricted so
 that it must extend @('subst_2'); and so on, until such @('s') is produced
 &mdash; or, the list of substitutions is exhausted without producing a
 matching substitution, in which case the rewrite or definition rule named
 @('x') is not applied to that term.  Finally, if @('x') is an event name
 corresponding to one or more @(':')@(tsee rewrite) or @(':')@(tsee definition)
 @(see rune)s (that is, @('x') is the ``base symbol'' of such @(see rune)s; see
 @(see rune)), say @(see rune)s @('r1'), ... @('rn'), then the meaning is the
 same except that @('(x subst_1 subst_2 ...)') is replaced by @('(rj subst_1
 subst_2 ...)') for each @('j').  Once this replacement is complete, the hint
 may not contain two members whose @(tsee car) is the same @(see rune).</p>

 <p>Note that the substitutions in @(':restrict') hints refer to the variables
 actually appearing in the goals, not to the variables appearing in the rule
 being restricted.</p>

 <p>The following example, supplied by Mihir Mehta, illustrates the use of
 @(':restrict') to handle free variables (in this case, a single free variable
 @('y')).  The call of @(tsee thm) below fails without the indicated
 @(':restrict') hint.</p>

 @({
  (defthm subsetp-trans
    (implies (and (subsetp x y) (subsetp y z)) (subsetp x z)))
  (defthm subsetp-evens (subsetp-equal (evens l) l))
  (thm (subsetp (evens (evens l)) l)
       :hints (("Goal" :restrict ((subsetp-trans ((y (evens l))))))))
 })

 <p>Here is another example, this one supplied by Bishop Brock.  Suppose that
 the database includes the following rewrite rule, which is probably kept @(see
 disable)d.  (We ignore the question of how to prove this rule.)</p>

 @({
  cancel-<-*$free:
  (implies (and (rationalp x)
                (rationalp y)
                (rationalp z))
           (equal (< y z)
                  (if (< x 0)
                      (> (* x y) (* x z))
                    (if (> x 0)
                        (< (* x y) (* x z))
                      (hide (< y z))))))
 })

 <p>Then ACL2 can prove the following theorem (unless other rules get in the
 way), essentially by multiplying both sides by @('x').</p>

 @({
  (thm
    (implies (and (rationalp x)
                  (< 1 x))
             (< (/ x) 1))
    :hints
    (("Goal"
      :in-theory (enable cancel-<-*$free)
      :restrict ((cancel-<-*$free ((x x) (y (/ x)) (z 1)))))))
 })

 <p>The @(':restrict') hint above says that the variables @('x'), @('y'), and
 @('z') in the rewrite rule @('cancel-<-*$free') above should be instantiated
 respectively by @('x'), @('(/ x)'), and @('1').  Thus @('(< y z)') becomes
 @('(< (/ x) 1)'), and this inequality is replaced by the corresponding
 instance of the right-hand-side of @('cancel-<-*$free').  Since the current
 conjecture assumes @('(< 1 x)'), that instance of the right-hand side
 simplifies to</p>

 @({
  (< (* x (/ x)) (* x 1))
 })

 <p>which in turn simplifies to @('(< 1 x)'), a hypothesis in the present
 theorem.</p></dd>

 <dt>@(':rw-cache-state')</dt><p/>

 <dd><p>@('Value') is an element of the list constant
 @('*legal-rw-cache-states*'): @(':atom') (the default), @('nil'), @('t'), or
 @(':disabled').  This hint applies to the indicated goal and all its
 descendants, to set the so-called ``rw-cache-state'' to the indicated value;
 see @(see set-rw-cache-state).</p></dd>

 <dt>@(':use')</dt><p/>

 <dd><p>Examples of @(':USE') hints are shown near the top of this
 documentation topic.</p>

 <p>@('Value') is a @(see lemma-instance) or a true list of @(see
 lemma-instance)s, indicating that the propositions denoted by the instances be
 added as hypotheses to the specified goal: that is, the @(':use') hint
 replaces a goal, @('G'), by the new goal, @('(IMPLIES P G)'), where @('P') is
 the theorem specified by the (conjunction of the) lemma instances provided.
 The @(':instance') form of a @(see lemma-instance) permits you to instantiate
 the free variables of previously proved theorems any way you wish, even
 allowing for differences in @(see packages); see @(see lemma-instance) for
 details.  These new hypotheses participate fully in all subsequent rewriting,
 etc.  If the goal in question is in fact an instance of a previously proved
 theorem, you may wish to use @(':by') (documented above).  Sometimes @(see
 theories) are helpful when employing @(':use') hints; see @(see
 minimal-theory).</p>

 <p>If the value is the name of a function symbol introduced by @(tsee defun),
 then the normalized (simplified) body of that definition is used; see @(see
 normalize).  This behavior differs from that provided by a @(':by') hint,
 where the original body of the definition is used.</p></dd>

 </dl>")

(defxdoc hints-and-the-waterfall
  :parents (hints)
  :short "How @(see hints) fit into the ACL2 proof waterfall"
  :long "<p>Below we describe the flow of an ACL2 proof attempt, with special
 attention to how @(see hints) are applied during a proof.  For most ACL2
 users, only one point is important to take away from this @(see documentation)
 topic: you may specify hints during a proof (see @(see hints); perhaps also
 see @(see computed-hints) and see @(see default-hints)), and they can be
 expected to behave intuitively.  See @(see the-method) for a summary of how to
 interact with the ACL2 prover; see @(see introduction-to-the-theorem-prover)
 for a more detailed tutorial; and see @(see hints) for an introduction to ACL2
 hints, including detailed @(see documentation) for specific hint types.</p>

 <p>The remainder of this topic serves as a reference in case one needs a
 deeper understanding of the workings of ACL2's handling of hints.  Also, for
 examples of the sophisticated use of hints, primarily for experts, see
 community book @('books/hints/basic-tests.lisp').</p>

 <p>First, we describe the ACL2 ``waterfall''.  Then, we describe how hints are
 handled by the waterfall.</p>

 <p><b>The Waterfall.</b></p>

 <p>The ACL2 <i>waterfall</i> is the heart of the ACL2 prover.  It attempts to
 prove a given goal and either completes the proof, fails, or produces goals to
 be proved by induction or forcing rounds.  The waterfall comprises a series of
 <i>steps</i>, such as simplification or generalization, each of which attempts
 to replace a given goal by zero or more subgoals whose provability implies
 provability of that goal.  Note that every proof by induction starts a new
 trip through the waterfall, as does every forcing round; and these occur only
 after all preceding trips through the waterfall are complete.  Let us see in
 more detail how the waterfall works.</p>

 <p>Each goal considered by the ACL2 prover passes through a series of proof
 processes, called the ``waterfall processes'', as stored in the constant
 @('*preprocess-clause-ledge*').  The top process applies top-level hints,
 including @(':use') hints; the next is a lightweight ``preprocess'' simplifier
 for ``simple'' rules (see @(see simple)); that is followed by the main ACL2
 simplifier and then the &ldquo;settled-down&rdquo; process described further
 below; and finally ACL2 attempts (in this order) destructor elimination,
 fertilization (heuristic use of equalities), generalization, and elimination
 of irrelevance.  See @(see architecture-of-the-prover) for more information on
 these processes.  Each process may ``hit'', creating zero or more child goals
 that are each then handled at the top of the waterfall; or it may ``miss'', in
 which case the next process in the above sequence is considered.  If all
 processes miss, then a ``push'' process defers the goal until it is later
 considered for proof by induction.  When all goals have been thus handled, the
 goal most recently pushed for proof by induction is considered, and the
 process repeats.</p>

 <p>We next describe the two additional ways in which control can be returned
 to the top of the waterfall.</p>

 <p>When the simplification process is attempted unsuccessfully for a goal, the
 goal is deemed to have ``settled down''.  This notion of ``settled down'' is
 handled, as follows, by the next waterfall process after simplification: the
 ``settled-down'' process.  If some ancestor of the goal (possibly the goal
 itself) has previously settled down, then the ``settled-down'' process is
 deemed to have missed on the goal.  Otherwise it hits on the goal, the effect
 being that the goal makes a new pass through all the waterfall
 processes.  (Other processes can then notice that settling down has occurred
 and modify their heuristics accordingly.)  For example, suppose that
 @('"Goal"') simplifies to @('"Subgoal 2"') (among others), and
 @('"Subgoal 2"') simplifies to @('"Subgoal 2.3"') (among others), which in
 turn is not further simplified.  Then the ``settled-down'' process hits on
 @('"Subgoal 2.3"'), but it does not hit not on any of its children or their
 children (and so on), because each of those has an ancestor, @('"Subgoal
 2.3"'), that has already been marked as ``settled-down''.</p>

 <p>The next proof process after settled-down is normally destructor
 elimination.  However, if a computed hint is suitable (in a sense described
 below; also see @(see computed-hints), especially the discussion of
 @('stable-under-simplificationp')), then that hint is selected as control is
 returned to the top of the waterfall.  A subtlety is that in this case, if the
 most recent hit had been from settling down, then the prover ``changes its
 mind'' and considers that the goal has not yet settled down after all as it
 continues through the waterfall.</p>

 <p>Each time a goal is considered at the top of the waterfall, then before
 passing through the proof processes as described above, ACL2 searches for a
 relevant hint to select unless it has already been provided a hint in the
 ``@('stable-under-simplificationp')'' case mentioned above.  We turn now to a
 more thorough discussion of how hints are selected and applied.</p>

 <p><b>The handling of hints.</b></p>

 <p>In the discussion below we will ignore forcing rounds, as each forcing
 round is simply treated as a new proof attempt that uses the list of hints
 provided at the start of the proof.</p>

 <p>When the theorem prover is called by @(tsee thm) or @(see events) such as
 @(tsee defthm), @(tsee defun), and @(tsee verify-guards), it gathers up the
 hints that have been supplied, often provided as a @(':')@(tsee hints)
 argument, but for example using a @(':guard-hints') argument for @(see guard)
 verification proofs.  (ACL2(r) users (see @(see real)) may also employ
 @(':std-hints').)  It then appends these to the front of the list of default
 hints (see @(see default-hints)).  The resulting list becomes the initial
 value of the list of ``pending hints'', one of two critical lists maintained
 by the theorem prover to manage hints.  The other critical list is a list of
 ``hint settings''; the two lists are maintained as follows.</p>

 <p>When a goal is first considered, a hint is selected from the list of
 pending hints if any is found to apply, as described below.  If a hint is
 selected, then it takes effect and is removed from the pending hints.  Except:
 if the selected hint is a computed hint with value @('t') specified for
 @(':computed-hint-replacement'), then it is not removed; and if that value is
 a list of hints, then that list is appended to the front of the list of
 pending hints after the selected hint is removed (also see @(see
 computed-hints)).  The selected hint is also used to update the hint settings,
 as described below.</p>

 <p>The list of hint settings associates hint keywords with values.  It is
 passed from the current goal to its children (and hence the children's
 children, and so on), though modified by hints selected from pending hints, as
 described below.  This list is maintained so that when a goal is pushed for
 proof by induction, the hint settings are applied at the start of the proof by
 induction.  Note that the list of hint settings is not re-applied to
 descendants of a goal in the current waterfall; a hint is applied only when it
 is selected (and also perhaps later as just described, through the stored hint
 settings at the start of a proof by induction).  For example, if the hint
 selected for @('"Subgoal 3"') includes @(':in-theory (enable foo)'), then
 the hint settings are correspondingly updated when processing @('"Subgoal
 3"'), and they persist at subgoals such as @('"Subgoal 3.2"') and
 @('"Subgoal 3.2.1"') (unless overridden by hints on those goals); but the
 theory specifying @('foo') is not re-installed at every such subgoal.</p>

 <p>When a hint is selected, the list of hint settings is updated so that for
 each keyword @(':kwd') and associated value @('val') from the hint, @(':kwd')
 is associated with @('val') in the hint settings, discarding any previous
 association of @(':kwd') with a value in the hint settings.  Except, certain
 ``top-level'' hints are never saved in the hint settings: @(':use'),
 @(':cases'), @(':by'), @(':bdd'), @(':or'), and @(':clause-processor').</p>

 <p>For example, suppose that we specify the following hints, with no default
 hints.</p>

 @({
  (("Goal" :expand ((bar x y)))
   ("Subgoal 3" :in-theory (enable foo)))
 })

 <p>These hints then become the initial list of pending hints.  When the proof
 attempt begins, the prover encounters the top-level goal (@('"Goal"')) and
 pulls the @('"Goal"') hint from the pending hints, so that the list of hint
 settings contains a value only for keyword @(':expand').  This hint setting
 will remain for all children of the top-level goal as well, and their
 children, and so on, and will be inherited by induction &mdash; in other
 words, it will remain throughout the entire proof.  Now consider what happens
 when the proof reaches @('"Subgoal 3"').  At this point there is only one
 pending hint, which is in fact attached to that subgoal.  Therefore, this hint
 is pulled from the pending hints (leaving that list empty), and the hint
 settings are extended by associating the @(':in-theory') keyword with the
 theory represented by @('(enable foo)').  That theory is immediately installed
 until the prover finishes addressing @('"Subgoal 3"'), its children, their
 children, and so on; and until that completion is reached, the @(':in-theory')
 keyword remains associated with the @('(enable foo)') in the hint settings,
 although of course there is no re-installation of the theory at any ensuing
 child goal.  When finally @('"Subgoal 3"') and its descendants have been
 completed and the prover is about to consider @('"Subgoal 2"'), the
 @(':in-theory') association is removed from the hint settings and the global
 theory is re-installed.  However, the list of pending hints remains empty.</p>

 <p>It remains to describe how a hint is selected for a goal.  When a goal is
 first considered (hence at the top of the waterfall), the list of pending
 hints is scanned, in order, until one of the hints is suitable for the goal.
 An explicit hint @('(goal-name :kwd1 val1 ... :kwdn valn)') is suitable if
 @('goal-name') is the name of the current goal and there is at least one
 keyword.  A computed hint is suitable if it evaluates to a non-@('nil') value.
 As indicated earlier in this documentation topic, an exception occurs when a
 computed hint is selected after simplification fails (the
 ``@('stable-under-simplificationp')'' case): in that case, the goal returns to
 the top of the waterfall with that hint as the selected hint, and no
 additional search for a hint to select is made at that time.</p>

 <p>The following slightly tricky example illustrates handling of hints.</p>

 @({
 ACL2 !>(set-default-hints '(("Goal" :do-not '(preprocess))))
  (("Goal" :DO-NOT '(PREPROCESS)))
 ACL2 !>(set-gag-mode nil)
 <state>
 ACL2 !>(thm (equal (append (append x y) z) (append x y z))
             :hints (("Goal" :in-theory (disable car-cons))))

  ACL2 Warning [Hints] in ( THM ...):  The goal-spec "Goal" is explicitly
  associated with more than one hint.  All but the first of these hints
  may be ignored.  If you intended to give all of these hints, consider
  combining them into a single hint of the form ("Goal" :kwd1 val1 :kwd2
  val2 ...). See :DOC hints and :DOC hints-and-the-waterfall; community
  book books/hints/merge-hint.lisp might also be helpful.

  [Note:  A hint was supplied for the goal above.  Thanks!]

  [Note:  A hint was supplied for the goal above.  Thanks!]

  Name the formula above *1.
 })

 <p>The warning above is printed because @('"Goal"') is associated with two
 pending hints: one given by the @(tsee set-default-hints) call and one
 supplied by the @(':')@(tsee hints) keyword of the @(tsee thm) form.  The
 @(':in-theory') hint is selected first because user-supplied hints are ahead
 of default hints in the list of pending hints; we then get the first
 &ldquo;Note&rdquo; above.  The goal progresses through the waterfall without
 any proof process applying to the goal; in particular, it cannot be further
 simplified.  After the simplification process, a &ldquo;settled-down&rdquo;
 process applies, as discussed above, immediately causing another trip through
 the waterfall.  Since the @(':in-theory') hint was earlier removed from the
 list of pending hints when it was applied, the default (@(':do-not')) hint is
 now the only pending hint.  That hint is applied, resulting in the second
 &ldquo;Note&rdquo; above.</p>

 <p>Again, more examples may be found in the community book
 @('books/hints/basic-tests.lisp').  A particularly tricky but informative
 example in that book is the one related to @('nonlinearp-default-hint').</p>

 <p>Also see @(see override-hints) for an advanced feature that allows
 modification of the hint selected for a goal.</p>")

(defxdoc history
  :parents (acl2)
  :short "Functions to display or change contents of the logical @(see world)"
  :long "<p>ACL2 keeps track of the @(see command)s that you have executed that
 have extended the logic or the rule database, as by the definition of macros,
 functions, etc.  Using the facilities in this section you can review the
 sequence of commands executed so far.  For example, you can ask to see the
 most recently executed command (by issuing @(':')@(tsee pc) @(':x')), or the
 preceding 10 commands (by issuing @(':')@(tsee pbt) @(':x-10')), or the
 command that introduced a given function symbol, @('fn') (by issuing @(':pc
 fn')).  You can also undo back through some previous command (see @(see ubt)),
 restoring the logical @(see world) to what it was before the given
 command.</p>

 <p>The annotations printed in the margin in response to some of these commands
 (including `P', `L', `V', `D', `d', 'M', and 'm') are explained in the
 documentation for @(':')@(tsee pc).</p>

 <p>Several technical terms are used in the documentation of the history
 commands.  You must understand these terms to use the commands.  These terms
 are documented with @(see documentation) entries of their own.  See @(see
 command), see @(see events), see @(see command-descriptor), and see @(see
 logical-name).</p>")

(defxdoc hons
  :parents (programming hons-and-memoization acl2-built-ins)
  :short "@('(hons x y)') returns a @(see normed) object equal to @('(cons x
  y)')."
  :long "<p>In the logic, @('hons') is just @(tsee cons); we leave it enabled
 and would think it odd to ever prove a theorem about it.</p>

 <p>Under the hood, @('hons') does whatever is necessary to ensure that its
 result is @(see normed).</p>

 <p>What might this involve?</p>

 <p>Since the car and cdr of any normed cons must be normed, we need to @(tsee
 hons-copy) x and y.  This requires little work if x and y are already normed,
 but can be expensive if x or y contain large, un-normed cons structures.</p>

 <p>After that, we need to check whether any normed cons equal to @('(x . y)')
 already exists.  If so, we return it; otherwise, we need to construct a new
 cons for @('(x . y)') and install it as the normed version of @('(x
 . y)').</p>

 <p>Generally speaking, these extra operations make @('hons') much slower than
 @('cons'), even when given normed arguments.</p>

 @(def hons)")

(defxdoc hons-acons
  :parents (fast-alists acl2-built-ins)
  :short "@('(hons-acons key val alist)') is the main way to create or extend
@(see fast-alists)."
  :long "<p>Logically, @('hons-acons') is like @(tsee acons) except that its
 guard does not require @(tsee alistp); we leave it enabled and would think it
 odd to ever prove a theorem about it.</p>

 <p>Under the hood, two things are done differently.  First, the key is copied
 with @(tsee hons-copy); this lets us use EQL-based hash tables instead of
 EQUAL-based hash tables for better performance.  Second, assuming there is a
 valid hash table associated with this alist, we destructively update the hash
 table by binding key to val.  The hash table will no longer be associated with
 alist, but will instead be associated with the new alist returned by
 @('hons-acons').</p>

 <p>Hash Table Creation</p>

 <p>A new hash table is created by @('hons-acons') whenever alist is an atom.
 Unlike ordinary @('acons'), we do not require that alist be nil, and in fact
 you may wish to use a non-nil value for one of two reasons.</p>

 <p>1.  As a size hint</p>

 <p>By default, the new hash table will be given a quite modest default
 capacity of 60 elements.  As more elements are added, the table may need to be
 resized to accommodate them, and this resizing has some runtime cost.</p>

 <p>When a natural number is used as a fast alist's name, we interpret it as a
 size hint.  For example, @('(hons-acons 'foo 'bar 1000)') instructs us to use
 1000 as the initial size for this hash table and binds 'foo to 'bar.  The
 resulting table should not need to be resized until more than 1000 elements
 are added.  We ignore size hints that request fewer than 60 elements.</p>

 <p>Because of hash collisions, hash tables typically need to have a larger
 size than the actual number of elements they contain.  The hash tables for
 fast alists are told to grow when they reach 70% full.  So, an easy rule of
 thumb might be: multiply the expected number of elements you need by 1.5 to
 keep your hash tables about 2/3 full.</p>

 <p>2.  As an alist name</p>

 <p>We also frequently use a symbol for alist, and think of this symbol as the
 name of the new alist.  We have found that naming alists can be valuable for
 two reasons:</p>

 <p>First, the name can be helpful in identifying fast alists that should have
 been freed, see @(tsee fast-alist-summary).</p>

 <p>Second, names can sometimes be used to avoid a subtle and insidious
 table-stealing phenomenon that occurs when using fast-alists that are
 themselves normed; see @(tsee hons-acons!).</p>

 <p>At the moment, there is no way to simultaneously name a fast alist and also
 give it a size hint.  We may eventually allow strings to include embedded name
 and size components, but for now we have not implemented this
 capability.</p>

 @(def hons-acons)")

(defxdoc hons-acons!
  :parents (fast-alists acl2-built-ins)
  :short "@('(hons-acons! key val alist)') is an alternative to @(tsee
hons-acons) that produces @(see normed), fast alists."
  :long "<p>Logically, @('hons-acons!') is like @(tsee acons) except that its
 guard does not require @(tsee alistp); we leave it enabled and would think it
 odd to ever prove a theorem about it.</p>

 <p>Ordinarily, @(see fast-alists) are constructed with @(tsee hons-acons)
 instead of @('hons-acons!').  In such alists, the keys are honsed, but the
 conses that make up the "spine" of the alist itself are ordinary conses.  In
 other words, it is basically correct to say:</p>

 @({
   (hons-acons key val alist) == (cons (cons (hons-copy key) val) alist)
 })

 <p>In contrast, when @('hons-acons!') is used, the conses making up the alist
 itself are also normed.  That is,</p>

 @({
   (hons-acons! key val alist) == (hons (hons key val) alist)
 })

 <p>Generally, you <b>should not use</b> @('hons-acons!') unless you really
 know what you're doing.</p>

 <p>Drawback 1.  @('hons-acons!') requires you to @(tsee hons-copy) all of the
 values that are being stored in the fast alist.  If you are storing large
 values, this may be expensive.</p>

 <p>Drawback 2.  It can be more difficult to maintain the proper discipline
 when using @('hons-acons!').  For instance, consider the following:</p>

 @({
    (let ((al1 (hons-acons 1 'one (hons-acons 2 'two nil)))
          (al2 (hons-acons 1 'one (hons-acons 2 'two nil))))
       ...)
 })

 <p>Here, both al1 and al2 are valid fast alists and they can be extended
 independently without any trouble.  But if these alists had instead been
 constructed with @('hons-acons!'), then since both al1 and al2 are equal,
 normed conses, they will literally be @(tsee eq) and hence will refer to
 precisely the same hash table.  In other words, @('hons-acons!') makes it
 relatively easy to <b>inadvertently</b> steal the hash table associated with
 some other fast alist.  This problem can be alleviated somewhat by uniquely
 naming alists; see the discussion in @(tsee hons-acons) for details.</p>

 <p>Despite these drawbacks, @('hons-acons!') is the typical way to generate a
 fast alist that is normed (but also, for example, see @(see
 fast-alist-fork!)).  It is not adequate to @(tsee hons-copy) a fast alist that
 was generated by ordinary @(tsee hons-acons) calls, because this would produce
 an EQUAL-but-not-EQ object, and this new object would not be associated with
 the fast alist's hash table.</p>

 @(def hons-acons!)")

(defxdoc hons-and-memoization
  :parents (acl2)
  :short "Hash cons, function memoization, and applicative hash tables"
  :long "<p>This topic describes the hash cons, function memoization, and
 applicative hash tables features available in ACL2, sometimes called the
 ``@(see hons-enabled)'' features.</p>

 <p>Bob Boyer and Warren Hunt, and later Jared Davis and Sol Swords, have
 developed a canonical representation for ACL2 data objects and a function
 memoization mechanism to facilitate reuse of previously computed results.
 This facility includes procedures to read and print ACL2 expressions in such a
 way that repetition of some ACL2 objects is eliminated, thereby permitting a
 kind of on-the-fly file compression.  The implementation does not alter the
 semantics of ACL2 except to add a handful of definitions.</p>

 <p>We historically gave the name ``ACL2(h)'' to the experimental extension of
 the ACL2 system including hash cons, function memoization, and fast
 association lists (applicative hash tables).  These features, which we call
 the ``@(see hons-enabled)'' features, are now present in ACL2.  The
 hons-enabled features are optimized for Clozure Common Lisp (CCL) and to some
 extent, GNU Common Lisp (GCL ANSI); but they are also supported in every ACL2
 build.</p>

 <p>Power users who want to take advantage of the @(see hons-enabled) features
 of ACL2 might find it helpful to consult the document @('centaur/README.html')
 in the ACL2 community books.</p>

 <p>Much of the documentation for the remainder of this topic is taken from the
 paper ``Function Memoization and Unique Object Representation for ACL2
 Functions'' by Robert S. Boyer and Warren A. Hunt, Jr., which has appeared in
 the Sixth International Workshop on the ACL2 Theorem Prover and Its
 Applications, ACM Digital Library, 2006.</p>

 <p>In the implementation of the ACL2 logic, ACL2 data objects are represented
 by Common Lisp objects of the same type, and the ACL2 pairing operation is
 internally implemented by the Common Lisp @(tsee cons) function.  In Common
 Lisp, @('cons') is guaranteed to provide a new pair, distinct from any
 previously created pair.  We have defined a new ACL2 function @(tsee HONS)
 that is logically identical to the ACL2 @('cons') function, but whose
 implementation usually reuses an existing pair if its components are identical
 to the components of an existing pair.  A record of ACL2 HONS objects is kept,
 and when an ACL2 function calls @('hons') ACL2 searches for an existing
 identical pair before allocating a new pair; this operation been called ``hash
 consing''.</p>

 <p>It appears that hash consing was first conceived by A. P. Ershov in 1957,
 to speed up the recognition of common subexpressions.  Ershov showed how to
 collapse trees to minimal DAGs by traversing trees bottom up, and he used
 hashing to eliminate the re-evaluation of common subexpressions.  In his 1973
 PhD dissertation L. Peter Deutsch describes a program verifier that uses hash
 cons to represent terms and his rewriter operated on hash consed terms.
 Later, Eiichi Goto implemented a Lisp system with a built-in hash consing
 operation: his h-CONS cells were rewrite protected and free of duplicate
 copies, and Goto used this hash consing operation to facilitate the
 implementation of a symbolic algebra system he developed.</p>

 <p>Memoizing functions also has a long history.  In 1967, Donald Michie
 proposed using memoized functions to improve the performance of machine
 learning.  Rote learning was improved by a learning function not forgetting
 what it had previously learned; this information was stored as memoized
 function values.</p>

 <p>The use of hash consing has appeared many times.  For instance, Henry Baker
 used hash consing to improve the performance of the well-known Boyer rewriting
 benchmark.  Baker used both hash consing and function memoization to improve
 the speed of the Takeuchi function, exactly in the spirit of our
 implementation, but without the automated, system-wide integration we report
 here.</p>

 <p>The ACL2 implementation permits memoization of user-defined functions.
 During execution a user may enable or disable function memoization on an
 individual function basis, may clear memoization tables, and may even keep a
 stack of memoization tables.  This facility takes advantage of our
 implementation where we keep one copy of each distinct ACL2 data object.  Due
 to the functional nature of ACL2, it is sufficient to have at most one copy of
 any data structure; thus, a user may arrange to keep data canonicalized.  This
 implementation extends to the entire ACL2 system the benefits enjoyed by BDDs:
 canonicalization, memoization, and fast equality check.</p>

 <p>We have defined various algorithms using these features, and we have
 observed, in some cases, substantial performance increases.  For instance, we
 have implemented unordered set intersection and union operations that operate
 in time roughly linear in the size of the sets.  Without using arrays, we
 defined a canonical representation for Boolean functions using ACL2 objects.
 We have investigated the performance of rewriting and tree consensus
 algorithms to good effect, and we believe function memoization offers
 interesting opportunities to simplify algorithm definition while
 simultaneously providing performance improvements.</p>

 <p>We recommend that users focus at first on the logical definitions of @(tsee
 hons) and other primitives rather than their underlying Common Lisp
 implementations.  Integrated with this memoization system is a performance
 monitoring system, which can provide real-time feedback on the operation and
 usefulness of @(tsee hons) and function memoization.  For a more detailed
 description of these tools, please see the ACL2 2006 workshop paper mentioned
 above.</p>

 <p>The Fibonacci function is a small example that demonstrates the utility of
 function memoization.  The following definition exhibits a runtime that is
 exponential in its input argument.</p>

 @({
  (defun fib (x)
    (declare (xargs :guard (natp x)))
    (mbe
     :logic
     (cond ((zp x) 0)
           ((= x 1) 1)
           (t (+ (fib (- x 1)) (fib (- x 2)))))
     :exec
     (if (< x 2)
         x
       (+ (fib (- x 1)) (fib (- x 2))))))
 })

 <p>Below we show how the ACL2 @(tsee time$) utility can measure the time to
 execute a call to the @('fib') function (with some editing to avoid noise from
 the underlying Common Lisp implementation).  @(tsee Memoize) is actually an
 ACL2 macro that expands to a call of the ACL2 function used to identify a
 function for memoization; see @(see memoize).  This function also accepts a
 well-formed term that must be true in order for the system to memoize a call
 of the memoized function; to ensure that an instance of the term is safe for
 evaluation in Common Lisp, a check is performed that if the @(see guard) of
 the memoized function is satisfied, then this instance will execute without
 error.</p>

 @({
  ACL2 !>(time$ (fib 40))
  ; (EV-REC *RETURN-LAST-ARG3* ...) took
  ; 0.99 seconds realtime, 0.98 seconds runtime
  ; (1,296 bytes allocated).
  102334155
  ACL2 !>(memoize 'fib)

  Summary
  Form:  ( TABLE MEMOIZE-TABLE ...)
  Rules: NIL
  Time:  0.01 seconds (prove: 0.00, print: 0.00, other: 0.01)

  Summary
  Form:  ( PROGN (TABLE MEMOIZE-TABLE ...) ...)
  Rules: NIL
  Time:  0.01 seconds (prove: 0.00, print: 0.00, other: 0.01)
   FIB
  ACL2 !>(time$ (fib 40))
  ; (EV-REC *RETURN-LAST-ARG3* ...) took
  ; 0.00 seconds realtime, 0.00 seconds runtime
  ; (2,864 bytes allocated).
  102334155
  ACL2 !>(time$ (fib 100))
  ; (EV-REC *RETURN-LAST-ARG3* ...) took
  ; 0.00 seconds realtime, 0.00 seconds runtime
  ; (7,024 bytes allocated).
  354224848179261915075
  ACL2 !>(unmemoize 'fib)
 })

 <p>We see that once the function @('fib') is identified as a function for
 which function calls should be memoized, the execution times are substantially
 reduced.  Finally, we can prevent @('fib') from being further memoized; in
 fact, @(tsee unmemoize) erases the previously memoized values.</p>

 <p>The implementation of hash consing, memoization, and applicative hash
 tables involves several facets: canonical representation of ACL2 data,
 function memoization, and the use of Lisp hash tables to improve the
 performance of association list operations.  We discuss each of these in turn,
 and we mention some subtle interrelationships.  Although it is not necessary
 to understand the discussion in this section, it may permit some users to
 better use this implementation.  This discussion may be confusing for some
 ACL2 users as it makes references to Lisp implementation features.</p>

 <p>The ACL2 system is actually implemented as a Lisp program that is layered
 on top of a Common Lisp system implementation.  ACL2 data constants are
 implemented with their corresponding counterparts in Common Lisp; that is,
 ACL2 cons pairs, strings, characters, numbers, and symbols are implemented
 with their specific Common Lisp counterparts.  This choice permits a number of
 ACL2 primitive functions to be implemented with their corresponding Common
 Lisp functions, but there are indeed differences.  ACL2 is a logic, and as
 such, it does not specify anything to do with physical storage or execution
 performance.  When ACL2 is used, the knowledgeable user can write functions to
 facilitate the reuse of some previously computed values.</p>

 <p>Recall the three mechanisms under discussion: hash consing, function
 memoization, and fast association list operations.  The function memoization
 mechanism takes advantage of the canonical representation of data objects
 provided by the @(tsee hons) operation as does the fast association list
 operation mechanism.  Each time @('hons') is invoked, its arguments are
 themselves converted, if necessary, to uniquely represented objects.</p>

 <p>The ACL2 universe is recursively closed under the @('cons') pairing
 operation and the atoms.  Hash consing (@(tsee hons)) is logically identical
 to @('cons'), but a set of tables is used to record each @('hons') pair.  When
 a @('hons') pair is requested, the implementation checks, in the current set
 of tables, whether the requested pair already exists.  If not, a new pair is
 created and a record of that pair is made; otherwise, a reference to the
 previously created pair is returned.  Thus, any data object created with
 @('hons') has a unique representation, as does every subcomponent.  We also
 arrange for strings to have a unique representation &mdash; only one copy of
 each different string is kept &mdash; and when any previously unseen string is
 an argument to @('hons'), we add the string to a unique table of strings.  A
 system-wide benefit of having a canonical representation for data is that
 equality comparisons between any two data objects can be done in constant
 time.</p>

 <p>The definition of @(tsee hons) in no way changes the operation of @('cons')
 &mdash; @('hons') creates a @('cons') pair.  When asked to create a @('hons'),
 the implementation checks to see if there is a @('cons') with the same @(tsee
 car) and @(tsee cdr) as the @('hons') being requested.  Thus, the only
 difference between the results of a @('hons') call and a corresponding
 @('cons') call is a notation in some invisible (to the ACL2 logic) tables
 where we record which @('cons') elements are also @('hons') elements.  Since a
 @('hons') is nothing but a @('cons'), the operation of @('car') and @('cdr')
 is unchanged.  In fact, the implementation is designed so that at any time it
 is safe to clear the table identifying which @('cons') elements are also
 considered @('hons') elements.</p>

 <p>User-defined functions with defined and verified guards can be memoized.
 When a function is memoized, a user-supplied condition restricts the domain
 when memoization is attempted.  When the condition is satisfied, memoization
 is attempted (assuming that memoization for the function is presently
 enabled); otherwise, the function is just evaluated.  Each memoized function
 has a hash table that is used to keep track of a unique list of function
 arguments paired with their values.  If appropriate, for each function the
 corresponding table is checked to see if a previous call with exactly the same
 arguments already exists in the table: if so, then the associated value is
 returned; if not, then the function is evaluated and a new key-value pair is
 added to the table of memoized values so that some future call will benefit
 from the memoization.  With ACL2 user functions memoization can be dynamically
 enabled and disabled.  There is an ACL2 function that clears a specific
 memoization table.  And finally, just as with the @('hons') table, a stack of
 these function memoization tables is maintained; that is, it is possible to
 memoize a function, use it a bit, set the memoized values aside, start a new
 table, use it, and then return to the original table.</p>

 <p>We next discuss the fast lookup operation for association lists.  When a
 pair is added to an association list using the functions @(tsee hons-acons) or
 @(tsee hons-acons!), the system also records the key-value pair in an
 associated hash table.  As long as a user only used these two functions when
 placing key-value pairs on an association list, the key-value pairs in the
 corresponding hash table will be synchronized with the key-value pairs in the
 association list.  Later, if @(tsee hons-get) is used to look up a key, then
 instead of performing a linear search of the association list we consult the
 associated hash table.  If a user does not strictly follow this discipline,
 then a linear search may be required.  In some sense, these association lists
 are much like ACL2 arrays, but without the burden of explicitly naming the
 arrays.  The ACL2 array @(tsee compress1) function is analogous to the
 functions @(tsee fast-alist-clean) and @(tsee fast-alist-clean!).  There are
 user-level ACL2 functions that allow the associated hash tables to be cleared
 and removed.</p>

 <p>As mentioned above, the @(see hons-enabled) features are optimized for CCL
 and GCL.  See @(see ccl-updates) for easy instructions for obtaining the
 latest version of CCL.</p>

 <p>REFERENCES</p>

 <p>Baker, Henry G., The Boyer Benchmark at Warp Speed. ACM Lisp Pointers V,3
 (Jul-Sep 1992), pages 13-14.</p>

 <p>Baker, Henry G., A Tachy 'TAK'.  ACM Lisp Pointers Volume 3,
 July-September, 1992, pages 22-23.</p>

 <p>Robert S. Boyer and Warren A. Hunt, Jr., Function Memoization and Unique
 Object Representation for ACL2 Functions, in the Sixth International Workshop
 on the ACL2 Theorem Prover and Its Applications, ACM Digital Library,
 2006.</p>

 <p>L.P. Deutsch. An Interactive Program Verifier. Tech. Rept. CSL-73-1, Xerox
 Palo Alto Research Center, May, 1973.</p>

 <p>A. P. Ershov.  On Programming of Arithmetic Operations.  In the
 Communications of the ACM, Volume 118, Number 3, August, 1958, pages
 427-430.</p>

 <p>Eiichi Goto, Monocopy and Associative Algorithms in Extended Lisp,
 TR-74-03, University of Tokyo, 1974.</p>

 <p>Richard P. Gabriel.  Performance and Evaluation of Lisp Systems.  MIT
 Press, 1985.</p>

 <p>Donald Michie.  Memo functions: a Language Feature with Rote Learning
 Properties.  Technical Report MIP-R-29, Department of Artificial Intelligence,
 University of Edinburgh, Scotland, 1967.</p>

 <p>Donald Michie.  Memo Functions and Machine Learning.  In Nature, Volume
 218, 1968, pages 19-22.</p>")

(defxdoc hons-assoc-equal
  :parents (fast-alists acl2-built-ins)
  :short "@('(hons-assoc-equal key alist)') is <b>not fast</b>; it serves as
the logical definition for @(tsee hons-get)."
  :long "<p>The definition of @('hons-assoc-equal') is similar to that of
 @(tsee assoc-equal), except that (1) it does not require @(tsee alistp) as a
 guard, and (2) it "skips over" any non-conses when its alist argument is
 malformed.</p>

 <p>We typically leave @('hons-get') enabled and reason about
 @('hons-assoc-equal') instead.  One benefit of this approach is that it avoids
 certain "false" discipline warnings that might arise from execution during
 theorem proving.</p>

 @(def hons-assoc-equal)")

(defxdoc hons-clear
  :parents (hons acl2-built-ins)
  :short "@('(hons-clear gc)') is a drastic garbage collection mechanism that
clears out the underlying Hons Space."
  :long "<p>Logically, @('hons-clear') just returns nil; we leave it enabled
 and would think it odd to ever prove a theorem about it.</p>

 <p>Under the hood, @('hons-clear') brutally (1) clears all the tables that
 govern which conses are @(see normed), then (2) optionally garbage collects,
 per the @('gc') argument, then finally (3) re-norms the keys of @(tsee
 fast-alists) and persistently normed conses; see @(see
 hons-copy-persistent).</p>

 <p>Notes.</p>

 <ul>

 <li>The hash tables making up the Hons Space retain their sizes after being
 cleared.  If you want to shrink them, see @(tsee hons-resize).</li>

 <li>CCL and GCL users might prefer @(tsee hons-wash), which is relatively
 efficient and allows for the garbage collection of normed conses without
 impacting their normed status.</li>

 <li>It is not recommended to interrupt this function.  Doing so may cause
 persistently normed conses and fast alist keys to become un-normed, which
 might lead to less efficient re-norming and/or violations of the fast-alist
 discipline.</li>

 <li>(For ACL2(p) users only; see @(see parallelism)) If parallel execution is
 enabled (see @(see set-parallel-execution)), as it is by default in ACL2(p),
 then @('hons-clear') may be a no-op (other than to print a warning), in order
 to avoid thread-unsafe behavior.  (However, In CCL you are unlikely to see
 this restriction unless you are running more than one thread.)  To get around
 this restriction, you can instead use @(tsee hons-clear!), which however
 requires a @(see trust-tag).</li>

 </ul>

 @(def hons-clear)")

(defxdoc hons-clear!
  :parents (hons acl2-built-ins)
  :short "A version of @(tsee hons-clear) for @(see parallel) execution"
  :long "<p>This function is only of interest to ACL2(p) users; see @(see
 parallelism), because for ACL2 it suffices to use @(tsee hons-clear).
 However, if parallel execution is enabled (see @(see set-parallel-execution)),
 as it is by default in ACL2(p), then @('hons-clear') may be a no-op (other
 than to print a warning), in order to avoid thread-unsafe behavior.  If you
 are not concerned about thread safety, for example when you want to call
 @('hons-clear') directly in the top-level loop, you can use @('hons-clear!'),
 which does not check for parallelism violations.  However, @('hons-clear!')
 requires a trust tag; see @(see defttag).</p>")

(defxdoc hons-copy
  :parents (hons acl2-built-ins)
  :short "@('(hons-copy x)') returns a @(see normed) object that is equal to
  X."
  :long "<p>In the logic, @('hons-copy') is just the identity function; we
 leave it enabled and would think it odd to ever prove a theorem about it.</p>

 <p>Under the hood, @('hons-copy') does whatever is necessary to produce a
 @(see normed) version of X.</p>

 <p>What might this involve?</p>

 <p>If X is a symbol, character, or number, then it is already normed and
 nothing is done.</p>

 <p>If X is a string, we check if any normed version of X already exists.  If
 so, we return the already-normed version; otherwise, we install X as the
 normed version for all strings that are @(tsee equal) to X.</p>

 <p>If X is a cons, we must determine if there is a normed version of X, or
 recursively construct and install one.  Norming large cons trees can become
 expensive, but there are a couple of cheap cases.  In particular, if X is
 already normed, or if large subtrees of X are already normed, then not much
 needs to be done.  The slowest case is norming some large ACL2 cons structure
 that has no subtrees which are already normed.</p>

 <p>Note that running @('hons-copy') on an object that was created with @(tsee
 cons) is often slower than just using @(tsee hons) directly when constructing
 the object.</p>

 @(def hons-copy)")

(defxdoc hons-copy-persistent
  :parents (hons acl2-built-ins)
  :short "@('(hons-copy-persistent x)') returns a @(see normed) object that is
equal to X and which will be re-normed after any calls to @(tsee hons-clear)."
  :long "<p>Logically @('hons-copy-persistent') is the identity; we leave it
 enabled and would think it odd to ever prove a theorem about it.</p>

 <p>Under the hood, @('hons-copy-persistent') is virtually identical to @(tsee
 hons-copy).</p>

 <p>The only difference is that when @(tsee hons-clear) is used, any
 persistently normed conses are automatically re-normed, and this re-norming
 can be carried out more efficiently than, say, an ordinary @(tsee
 hons-copy).</p>

 @(def hons-copy-persistent)")

(defxdoc hons-enabled
  :parents (hons-and-memoization)
  :short "Hash cons, function memoization, and applicative hash tables"
  :long "<p>ACL2 supports hash cons, function memoization, and applicative hash
 tables; see @(see hons-and-memoization).  These are sometimes called the
 ``hons-enabled features'' of ACL2.</p>")

(defxdoc hons-equal
  :parents (hons equal acl2-built-ins)
  :short "@('(hons-equal x y)') is a recursive equality check that optimizes
when parts of its arguments are @(see normed)."
  :long "<p>In the logic, @('hons-equal') is just @(tsee equal); we leave it
 enabled and would think it odd to ever prove a theorem about it.</p>

 <p>Under the hood, when @('hons-equal') encounters two arguments that are both
 normed, it becomes a mere @(tsee eql) check, and hence avoids the overhead of
 recursively checking large cons structures for equality.</p>

 <p>Note.  If @('hons-equal') is given arguments that do not contain many
 normed objects, it can actually be much slower than @(tsee equal)!  This is
 because it checks to see whether its arguments are normed at each recursive
 step, and so you are repeatedly paying the price of such checks.  Also see
 @(see hons-equal-lite), which only checks at the top level whether its
 arguments are normed.</p>

 @(def hons-equal)")

(defxdoc hons-equal-lite
  :parents (hons hons-equal)
  :short "@('(hons-equal-lite x y)') is a non-recursive equality check that
optimizes if its arguments are @(see normed)."
  :long "<p>In the logic, @('hons-equal-lite') is just @(tsee equal); we leave
 it enabled and would think it odd to ever prove a theorem about it.</p>

 <p>Under the hood, @('hons-equal-lite') checks whether its arguments are
 normed, and if so it effectively becomes a @(tsee eql) check.  Otherwise, it
 immediately calls @(tsee equal) to determine if its arguments are equal.</p>

 <p>The idea here is to strike a useful balance between @('equal') and @(tsee
 hons-equal).  If both arguments happen to be normed, we get to use a very fast
 equality comparison.  Otherwise, we just get out of the way and let @('equal')
 do its work, without the extra overhead of recursively checking whether the
 subtrees of x and y are normed.</p>

 @(def hons-equal-lite)")

(defxdoc hons-get
  :parents (fast-alists acl2-built-ins)
  :short "@('(hons-get key alist)') is the efficient lookup operation for @(see
fast-alists)."
  :long "<p>Logically, @('hons-get') is just an alias for @(tsee
 hons-assoc-equal); we typically leave it enabled and prefer to reason about
 @('hons-assoc-equal') instead.  One benefit of this approach is that it helps
 to avoids "false" discipline warnings that might arise from execution during
 theorem proving.</p>

 <p>Under the hood, when @('alist') is a fast alist that is associated with a
 valid hash table, @('hons-get') first norms @('key') using @(tsee hons-copy),
 then becomes a @('gethash') operation on the hidden hash table.  Otherwise
 @('hons-get') simply invokes @(tsee hons-assoc-equal), which is similar (in
 definition and in performance) to @(tsee assoc-equal), on @('key') and
 @('alist').</p>

 @(def hons-get)")

(defxdoc hons-note
  :parents (hons)
  :short "Notes about @(see HONS), especially pertaining to expensive resizing
 operations"
  :long "<p>Certain ``Hons-Notes'' are printed to the terminal to report
 implementation-level information about the management of @(see HONS)
 structures.  Some of these may be low-level and of interest mainly to system
 developers.  But below we discuss what users can learn from a particular
 hons-note, ``ADDR-LIMIT reached''.  In short: If you are seeing a lot of such
 hons-notes, then you may be using a lot of memory.  (Maybe you can reduce that
 memory; for certain BDD operations, for example (as defined in community books
 @('books/centaur/ubdds/')), variable ordering can make a big difference.)</p>

 <p>By way of background:</p>

 <blockquote><p>The ADDR-HT is the main hash table that lets us look up @(see
 normed) conses, i.e., @(see hons)es.  It is an ordinary Common Lisp hash
 table, so when it starts to get too full the Lisp will grow it.  It can get
 really big.  (It has been seen to take more than 10 GB of memory just for the
 hash table's array, not to mention the actual conses!)</p>

 <p>Hons-Notes may be printed when the ADDR-HT is getting really full.  This
 growth can be expensive and can lead to memory problems.  Think about what it
 takes to resize a hash table:</p>

 <p>(1) allocate a new, bigger array<br></br>

   (2) rehash elements, copying them into the new array<br></br>

   (3) free the old array</p>

 <p>Until you reach step (3) and a garbage collection takes place, you have to
 have enough memory to have both the old and new arrays allocated.  If the old
 array was 10 GB and we want to allocate a new one that's 15 GB, this can get
 pretty bad.  Also, rehashing the elements is expensive time-wise when there
 are lots of elements.</p>

 <p>Since resizing a hash table is expensive, we want to avoid it.  There's a
 @(tsee hons-resize) command for this.  You may want your books to start with
 something like the following.</p>

 @({
    (value-triple (set-max-mem (* 30 (expt 2 30))))      ; 30 GB heap
    (value-triple (hons-resize :addr-ht #u_100_000_000)) ; 100M honses
 })

 <p>Basically, if you roughly know how many honses your book will need, you can
 just get them up front and then never to resize.</p></blockquote>

 <p>The Hons-Notes about ``ADDR-LIMIT reached'' are basically there to warn you
 that the ADDR-HT is being resized.  This can help you realize that your @(tsee
 hons-resize) command had too small of an ADDR-HT size, or might suggest that
 your book should have a @(tsee hons-resize) command.  There are also commands
 like @('(')@(tsee hons-summary)@(')'), @(see set-max-mem), and defined in
 community book @('books/centaur/misc/memory-mgmt-logic.lisp'),
 @('(hons-analyze-memory nil)').  These can show you how many honses you
 currently have, how much space they are taking, and that sort of thing.  (A
 nice trick is to call @(tsee hons-summary) at the end of a book, to get an
 idea of how many honses you should ask for in your @(tsee hons-resize)
 command).</p>")

(defxdoc hons-resize
  :parents (hons acl2-built-ins)
  :short "@('(hons-resize ...)') can be used to manually adjust the sizes of
the hash tables that govern which ACL2 Objects are considered @(see normed)."
  :long "<p>General form:</p>

 @({
   (hons-resize [:str-ht size]
                [:nil-ht size]
                [:cdr-ht size]
                [:cdr-ht-eql size]
                [:addr-ht size]
                [:other-ht size]
                [:sbits size]
                [:fal-ht size]
                [:persist-ht size])
 })

 <p>Example:</p>

 @({
   (hons-resize :str-ht 100000
                :addr-ht (expt 2 27))
 })

 <p>Logically, @('hons-resize') just returns nil; we leave it enabled and would
 think it odd to ever prove a theorem about it.</p>

 <p>Under the hood, @('hons-resize') can be used to change the sizes of certain
 hash tables in the Hons Space.</p>

 <p>All arguments are optional.  The size given to each argument should either
 be nil (the default) or a natural number.  A natural number indicates the
 newly desired size for the hash table, whereas nil means "don't resize this
 table." Any non-natural argument is regarded as nil.</p>

 <p>You may wish to call this function for two reasons.</p>

 <p>1.  Improving Performance by Resizing Up</p>

 <p>Since the hash tables in the Hons Space automatically grow as new objects
 are normed, @('hons-resize') is unnecessary.  But automatic growth can be slow
 because it is incremental: a particular hash table might be grown dozens of
 times over the course of your application.  Using @('hons-resize') to pick a
 more appropriate initial size may help to reduce this overhead.</p>

 <p>2.  Reducing Memory Usage by Resizing Down</p>

 <p>Resizing can also be used to shrink the hash tables.  This might possibly
 be useful immediately after a @(tsee hons-clear) to free up memory taken by
 the hash tables themselves.  (Of course, the tables will grow again as you
 create new normed objects.)</p>

 <p>Advice for using @('hons-resize').</p>

 <p>Note that hash tables that are already close to the desired size, or which
 have too many elements to fit into the desired size, will not actually be
 resized.  This makes resizing relatively "safe."</p>

 <p>Note that the @(tsee hons-summary) function can be used to see how large
 and how full your hash tables are.  This may be useful in deciding what sizes
 you want to give to @('hons-resize').</p>

 <p>Note that @('hons-resize') operates by (1) allocating new hash tables, then
 (2) copying everything from the old hash table into the new table.  Because of
 this, for best performance you should ideally call it when the hash tables
 involved are minimally populated, i.e., at the start of your application, or
 soon after a @(tsee hons-clear).</p>")

(defxdoc hons-shrink-alist
  :parents (fast-alist-fork acl2-built-ins)
  :short "Deprecated feature"
  :long "<p>Deprecated.  Alias for @(tsee fast-alist-fork).</p>")

(defxdoc hons-shrink-alist!
  :parents (fast-alist-fork! acl2-built-ins)
  :short "Deprecated feature"
  :long "<p>Deprecated.  Alias for @(tsee fast-alist-fork!).</p>")

(defxdoc hons-summary
  :parents (hons acl2-built-ins)
  :short "@('(hons-summary)') prints basic information about the sizes of the
tables in the current Hons Space."
  :long "<p>Logically, @('hons-summary') just returns nil; we leave it enabled
 and would think it odd to ever prove a theorem about it.</p>

 <p>Under the hood, this function gathers and prints some basic information
 about the sizes of the tables in the Hons Space.</p>

 <p>This information may be useful for deciding if you want to garbage collect
 using functions such as @(tsee hons-clear) or @(tsee hons-wash).  It may also
 be useful for determining good initial sizes for the Hons Space hash tables
 for your particular computation; see @(see hons-resize).  For information
 about @(see fast-alists), see @(see fast-alist-summary).</p>

 @(def hons-summary)")

(defxdoc hons-wash
  :parents (hons acl2-built-ins)
  :short "@('(hons-wash)') is like @(tsee gc$) but can also garbage collect
@(see normed) objects (CCL and GCL Only)."
  :long "<p>Logically, @('hons-wash') just returns nil; we leave it enabled and
 would think it odd to ever prove a theorem about it.</p>

 <p>Under the hood, in CCL and GCL, @('hons-wash') runs a garbage collection
 after taking special measures to allow normed conses to be collected.  In
 Lisps other than CCL, @('hons-wash') does nothing.  This is because the
 efficient implementation of @('hons-wash') is specific to the "static
 honsing" scheme which requires CCL-specific features.</p>

 <p>Why is this function needed?  Ordinarily, it is not possible to garbage
 collect any normed conses.  This is because the Hons Space includes pointers
 to any normed conses, and hence Lisp's garbage collector thinks these objects
 are live.  To correct for this, @('hons-wash') (1) clears out these pointers,
 (2) runs a garbage collection, then (3) re-norms any previously-normed conses
 which have survived the garbage collection.</p>

 <p>Notes.</p>

 <ul>

 <li>It is not recommended to interrupt this function.  Doing so may cause
 persistently normed conses and fast alist keys to become un-normed, which
 might lead to less efficient re-norming and/or violations of the fast-alist
 discipline.</li>

 <li>(For ACL2(p) users only; see @(see parallelism)) If parallel execution is
 enabled (see @(see set-parallel-execution)), as it is by default in ACL2(p),
 then @('hons-wash') may be a no-op (other than to print a warning), in order
 to avoid thread-unsafe behavior.  (However, In CCL you are unlikely to see
 this restriction unless you are running more than one thread.)  To get around
 this restriction, you can instead use @(tsee hons-wash!), which however
 requires a @(see trust-tag).</li>

 </ul>

 @(def hons-wash)")

(defxdoc hons-wash!
  :parents (hons acl2-built-ins)
  :short "A version of @(tsee hons-wash) for @(see parallel) execution"
  :long "<p>This function is only of interest to ACL2(p) users; see @(see
 parallelism), because for ACL2 it suffices to use @(tsee hons-wash).  However,
 if parallel execution is enabled (see @(see set-parallel-execution)), as it is
 by default in ACL2(p), then @('hons-wash') may be a no-op (other than to print
 a warning), in order to avoid thread-unsafe behavior.  If you are not
 concerned about thread safety, for example when you want to call
 @('hons-wash') directly in the top-level loop, you can use @('hons-wash!'),
 which does not check for parallelism violations.  However, @('hons-wash!')
 requires a trust tag; see @(see defttag).</p>")

(defxdoc |Hey Wait!  Is ACL2 Typed or Untyped(Q)|
  :parents (|Pages Written Especially for the Tours|)
  :short "Hey Wait!  Is ACL2 Typed or Untyped?"
  :long "<p>The example</p>

 <code>
 ACL2 !&gt;<b>(app 7 27)</b>

 ACL2 Error in TOP-LEVEL:  The guard for the function symbol ENDP, which
 is (OR (CONSP X) (EQUAL X NIL)), is violated by the arguments in the
 call (ENDP 7).
 </code>

 <p>illustrates the fact that while ACL2 is an untyped language the ACL2
 evaluator can be configured so as to check ``types'' at runtime.  We should
 not say ``types'' here but ``guards.''  See @(see |Guards in ACL2|) for a
 discussion of guards.</p>

 <p>The guard on @(tsee endp) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>
 requires its argument to be a true list.  Since 7 is not a true list, and
 since ACL2 is checking guards in this example, an error is signaled by ACL2.
 How do you know ACL2 is checking guards?  Because the prompt tells us (click
 <see topic='@(url |About the Prompt|)'>here</see>) with its ``!''.</p>")

(defxdoc |How Long Does It Take to Become an Effective User(Q)|
  :parents (|Pages Written Especially for the Tours|)
  :short "How Long Does It Take to Become an Effective User?"
  :long "<p><see topic='@(url |Other Requirements|)'><img
 src='res/tours/flying.gif'></img></see></p>

 <p>We expect that a talented undergraduate majoring in computer science (or
 perhaps mathematics) will probably take several weeks to become an effective
 ACL2 user.  The time will depend, of course, on that student's familiarity
 with logic (or formal methods) and Lisp programming, as well as willingness to
 read and study the ACL2 User's Manual.</p>

 <p>Of course, it is critical to do some projects in order to gain proficiency.
 (Hence access to an ACL2 implementation is also a requirement, for example by
 downloading and installing following links from the ACL2 home page.)  But it
 is critical to start with ``toy'' projects before tackling a ``grand
 challenge.''</p>

 <p><see topic='@(url |Other Requirements|)'><img
 src='res/tours/flying.gif'></img></see></p>")

(defxdoc how-to-contribute
  :parents (about-acl2 community)
  :short "Guide to contributing code to ACL2."
  :long "<p>The main way to contribute code to ACL2 is to open a pull request
 (PR) to the <a href='https://github.com/acl2/acl2'>ACL2 GitHub
 repository</a>.  First create a personal fork of the
 repository and commit your changes/additions there.  Then open a
 PR to merge your changes into the main ACL2 repository.  Please ensure
 your PR follows these guidelines:</p>

 <h3>Required: Make Changes Only Within the @('books/') Directory</h3>

 <p>While the community is invited to submit contributions to the <see
 topic='@(url community-books)'>Community Books</see>, source files outside of
 the @('books/') directory should not be modified, except by system
 maintainers.</p>

 <p>Suggestions for system changes can be emailed to <a
 href='mailto:kaufmann@cs.utexas.edu'>Matt Kaufmann</a>. (Prospective system
 developers should see the @(see developers-guide).)</p>

 <p>New developments that do not clearly belong in an existing directory
 are often put into the @(tsee projects) subdirectory of @('books/').</p>

 <h3>Required: Avoid Problematic Constructs</h3>

 <p>Avoid introducing code that may fail on machines/environments
  other than your own.  In particular, avoid the following:</p>

         <ul>

         <li>Dependence on any files not included in your PR.  In particular,
         any book that depends on an external tool, such as an SMT solver,
         should include an appropriate <see topic='@(url
         build::cert_param)'>cert_param</see>.</li>

         <li>Dependence on environment variables that will not be set in other
         users' environments.</li>

         <li>Use of absolute pathnames (e.g., mentions of your home directory).
         These are likely to cause problems for other users.  To bring in other
         Community Books, use the @(':dir :system') option of @(tsee
         include-book).</li>

         <li>Constructs with timeouts that cause proof attempts to be aborted
         after a short time.  These may cause failures on slower or heavily
         loaded machines.</li>

         </ul>

 <h3>Required: Check the Build</h3>

 <p>Before making your PR, you should run a regression to ensure that
 your changes/additions do not break the build. To do so, run the following
 @('make') command in the ``books'' directory:</p>

 @({
   make -j 8 regression
 })

 <p>(Note: the @('-j 8') option in the above command is only illustrative. It
 instructs @('make') to use 8 hardware threads. You may use a higher or lower
 number to align with your system. See @(see books-certification) for an
 extended discussion on community book certification.)</p>

 <h3>Required: Change the Base Branch of your PR to @('testing')</h3>

 <p>When opening your PR to merge changes into the main ACL2 repository, set
 the base branch to the @('testing') branch (or similar) (<i>not</i> the
 @('master') branch).  Once your PR is accepted into the @('testing') branch,
 it will be tested and merged automatically into the @('master') branch if all
 tests pass.</p>

 <h3>Suggested: Follow Best Practices for ACL2 Code</h3>

 <p>See @(see best-practices) for recommended code practices.</p>

 <h3>Suggested: Document Your New Books</h3>

 <p>Consider creating documentation using the @(tsee xdoc) system.  Then, to
 ensure your new topics appear in the manual, ensure they are included by
 @('books/doc/top.lisp'), perhaps via another book that it includes, such as
 @('books/projects/top-doc.lisp').</p>

 <h3>Suggested: Update the Release Notes</h3>

 <p>Consider adding some high-level information about your changes to the
 Community Books' release notes &mdash; i.e., the appropriate @(see
 release-notes-books) XDOC topic in @('books/doc/relnotes.lisp').</p>

 <h3>Resources for Git/GitHub</h3>

 <p>For those new to Git (the version control system) or GitHub (the platform
 on which the ACL2 Git repository is hosted), see @(see git-quick-start).</p>

 <h3>Frequent Contributors</h3>

 <p>Frequent contributors may request to join the <a
 href='https://github.com/acl2/acl2'>ACL2 GitHub project</a>. Such contributors may
 push directly to various testing branches without opening a PR (although it is
 still good practice to open a PR when modifying a widely used book or one
 primarily authored by someone else).</p>

 <p>To request to join the project, email one of the following
 individuals:</p>
 <ul>
   <li>Eric Smith (@('eric.smith@kestrel.edu'))</li>
   <li>David Rager (@('ragerdl@gmail.com'))</li>
   <li>Sol Swords (@('sswords@gmail.com'))</li>
 </ul>

 <p>See also the @(see community) topic for other ways to connect with the ACL2
 community, and ways to get help.</p>")

(defxdoc |How To Find Out about ACL2 Functions|
  :parents (|Pages Written Especially for the Tours|)
  :short "How To Find Out about ACL2 Functions"
  :long "<p><see topic='@(url
 |How To Find Out about ACL2 Functions (cont)|)'><img
 src='res/tours/walking.gif'></img></see></p>

 <p>Most ACL2 primitives are documented.  Here is the definition of @('app')
 again, with the documented topics highlighted.  <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>
 All of the links below lead into the ACL2 User's Manual.  So follow these
 links if you wish, but use your <b>Back Button</b> to return here!</p>

 <code>
 (@(see defun) app (x y)
   (@(see cond) ((@(see endp) x) y)
         (t (@(see cons) (@(see car) x)
                  (app (@(see cdr) x) y)))))
 </code>

 <p>By following the link on @(see endp) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see> we
 see that it is a Common Lisp function and is defined to be the same as @(see
 atom) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>, which recognizes non-conses.  But @('endp') has a
 guard.  Since we are ignoring guards for now, we'll ignore the guard issue on
 @('endp').</p>

 <p>So this definition reads ``to @('app') @('x') and @('y'): if @('x') is an
 atom, return @('y'); otherwise, @('app') @('(cdr x)') and @('y') and then cons
 @('(car x)') onto that.''</p>

 <p><see topic='@(url |How To Find Out about ACL2 Functions (cont)|)'><img
 src='res/tours/walking.gif'></img></see></p>")

(defxdoc |How To Find Out about ACL2 Functions (cont)|
  :parents (|Pages Written Especially for the Tours|)
  :short "How To Find Out about ACL2 Functions (cont)"
  :long "<p><see topic='@(url |The Admission of App|)'><img
 src='res/tours/walking.gif'></img></see></p>

 <p>The ACL2 documentation is also available in Emacs, via the ACL2-Doc
 browser (see @(see ACL2-Doc)) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>,
 allowing you to explore the hyperlinked documentation in the comfort of a text
 editor that can also interact with ACL2.</p>

 <p>In addition, runtime images of ACL2 have the hyperlinked text as a large
 ACL2 data structure that can be explored with ACL2's <b>:doc</b> command.  If
 you have ACL2 running, try the command <b>:doc endp</b>.</p>

 <p>Another way to find out about ACL2 functions, if you have an ACL2 image
 available, is to use the command @(':')@(tsee args) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>
 which prints the formals, type, and guard of a function symbol.</p>

 <p>Of course, the ACL2 documentation can also be printed out as a very long
 book but we do not recommend that!  See the ACL2 Home Page to download the
 Postscript.</p>

 <p>Now let's continue with @('app').</p>

 <p><see topic='@(url |The Admission of App|)'><img
 src='res/tours/walking.gif'></img></see></p>")

(defxdoc i-am-here
  :parents (ld)
  :short "A convenient marker for use with @(tsee rebuild) or @(tsee ld)"
  :long "@({
  Example Input File for Rebuild:
  (defun fn1 (x y) ...)
  (defthm lemma1 ...)
  (defthm lemma2 ...)
  (i-am-here)
  The following lemma won't go through.  I started
  typing the hint but realized I need to prove a
  lemma first.  See the failed proof attempt in foo.bar.
  I'm going to quit for the night now and resume tomorrow
  from home.

  (defthm lemma3 ...
    :hints (("Goal" :use (:instance ???
  ...
 })

 <p>By putting an @('(i-am-here)') form at the ``frontier'' of an evolving file
 of @(see command)s, you can use @(tsee rebuild) to load the file up to the
 @('(i-am-here)').  @('I-am-here') simply returns an @(see error-triple) that
 indicates an error, and any form that ``causes an error'' will do the same
 job.  Note that the text of the file after the @('(i-am-here)') need not be
 machine readable.</p>")

(defxdoc i-close
  :parents (real)
  :short "ACL2(r) test for whether two numbers are infinitesimally close"
  :long "<p>@('(I-close x y)') is true if and only if @('x-y') is an
 infinitesimal number.  This predicate is only defined in ACL2(r) (see @(see
 real)).</p>")

(defxdoc i-large
  :parents (real)
  :short "ACL2(r) recognizer for infinitely large numbers"
  :long "<p>@('(I-large x)') is true if and only if @('x') is non-zero and
 @('1/x') is an infinitesimal number.  This predicate is only defined in
 ACL2(r)
 (see @(see real)).</p>")

(defxdoc i-limited
  :parents (real)
  :short "ACL2(r) recognizer for limited numbers"
  :long "<p>@('(I-limited x)') is true if and only if @('x') is a number that
 is not infinitely large.  This predicate is only defined in ACL2(r)
 (see @(see real)).</p>")

(defxdoc i-small
  :parents (real)
  :short "ACL2(r) recognizer for infinitesimal numbers"
  :long "<p>@('(I-small x)') is true if and only if @('x') is an infinitesimal
 number (possibly 0).  This predicate is only defined in ACL2(r)
 (see @(see real)).</p>")

(defxdoc identity
  :parents (basics acl2-built-ins)
  :short "The identity function"
  :long "<p>@('(Identity x)') equals @('x'); what else can we say?</p>

 <p>@('Identity') is a Common Lisp function.  See any Common Lisp documentation
 for more information.</p>

 @(def identity)")

(defxdoc if
  :parents (basics acl2-built-ins)
  :short "If-then-else function"
  :long "<p>@('(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').</p>

 <p>Only one of @('y'), @('z') is evaluated when @('(if x y z)') is
 evaluated.</p>

 <p>@('If') has a @(see guard) of @('t').</p>

 <p>@('If') is part of Common Lisp.  See any Common Lisp documentation for more
 information.</p>")

(defxdoc if*
  :parents (bdd)
  :short "For conditional rewriting with BDDs"
  :long "<p>The function @('IF*') is defined to be @(tsee IF), but it is used
 in a special way by ACL2's @(see BDD) package.</p>

 @(def if*)

 <p>As explained elsewhere (see @(see bdd-algorithm)), ACL2's @(see BDD)
 algorithm gives special treatment to @(see term)s of the form @('(IF* TEST TBR
 FBR)').  In such cases, the algorithm simplifies @('TEST') first, and the
 result of that simplification must be a constant (normally @('t') or @('nil'),
 but any non-@('nil') explicit value is treated like @('t') here).  Otherwise,
 the algorithm aborts.</p>

 <p>Thus, @('IF*') may be used to implement a sort of conditional rewriting for
 ACL2's @(see BDD) package, even though this package only nominally supports
 unconditional rewriting.  The following contrived example should make this
 point clear.</p>

 <p>Suppose that we want to prove that @('(nthcdr (length x) (append x y))') is
 equal to @('y'), but that we would be happy to prove this only for lists
 having length 4.  We can state such a theorem as follows.</p>

 @({
  (let ((x (list x0 x1 x2 x3)))
    (equal (nthcdr (length x) (append x y))
           y))
 })

 <p>If we want to prove this formula with a @(':')@(tsee BDD) hint, then we
 need to have appropriate rewrite rules around.  First, note that @('LENGTH')
 is defined as follows (try @(':')@(tsee PE) @(tsee LENGTH)):</p>

 @({
  (length x)
   =
  (if (stringp x)
      (len (coerce x 'list))
      (len x))
 })

 <p>Since @(see BDD)-based rewriting is merely very simple unconditional
 rewriting (see @(see bdd-algorithm)), we expect to have to prove a rule
 reducing @(tsee STRINGP) of a @(tsee CONS):</p>

 @({
  (defthm stringp-cons
    (equal (stringp (cons x y))
           nil))
 })

 <p>Now we need a rule to compute the @('LEN') of @('X'), because the
 definition of @('LEN') is recursive and hence not used by the @(see BDD)
 package.</p>

 @({
  (defthm len-cons
    (equal (len (cons a x))
           (1+ (len x))))
 })

 <p>We imagine this rule simplifying @('(LEN (LIST X0 X1 X2 X3))') in terms of
 @('(LEN (LIST X1 X2 X3))'), and so on, and then finally @('(LEN nil)') should
 be computed by execution (see @(see bdd-algorithm)).</p>

 <p>We also need to imagine simplifying @('(APPEND X Y)'), where still @('X')
 is bound to @('(LIST X0 X1 X2 X3)').  The following two rules suffice for this
 purpose (but are needed, since @(tsee APPEND), actually @(tsee BINARY-APPEND),
 is recursive).</p>

 @({
  (defthm append-cons
    (equal (append (cons a x) y)
           (cons a (append x y))))

  (defthm append-nil
    (equal (append nil x)
           x))
 })

 <p>Finally, we imagine needing to simplify calls of @(tsee NTHCDR), where the
 first argument is a number (initially, the length of @('(LIST X0 X1 X2 X3)'),
 which is 4).  The second lemma below is the traditional way to accomplish that
 goal (when not using BDDs), by proving a conditional rewrite rule.  (The first
 lemma is only proved in order to assist in the proof of the second lemma.)</p>

 @({
  (defthm fold-constants-in-+
    (implies (and (syntaxp (quotep x))
                  (syntaxp (quotep y)))
             (equal (+ x y z)
                    (+ (+ x y) z))))

  (defthm nthcdr-add1-conditional
    (implies (not (zp (1+ n)))
             (equal (nthcdr (1+ n) x)
                    (nthcdr n (cdr x)))))
 })

 <p>The problem with this rule is that its hypothesis makes it a conditional
 @(see rewrite) rule, and conditional rewrite rules are not used by the @(see
 BDD) package.  (See @(see bdd-algorithm) for a discussion of ``BDD rules.'')
 (Note that the hypothesis cannot simply be removed; the resulting formula
 would be false for @('n = -1') and @('x = '(a)'), for example.)  We can solve
 this problem by using @('IF*'), as follows; comments follow.</p>

 @({
  (defthm nthcdr-add1
    (equal (nthcdr (+ 1 n) x)
           (if* (zp (1+ n))
                x
                (nthcdr n (cdr x)))))
 })

 <p>How is @('nthcdr-add1') applied by the @(see BDD) package?  Suppose that
 the @(see BDD) computation encounters a @(see term) of the form @('(NTHCDR (+
 1 N) X)').  Then the @(see BDD) package will apply the @(see rewrite) rule
 @('nthcdr-add1').  The first thing it will do when attempting to simplify the
 right hand side of that rule is to attempt to simplify the term @('(ZP (1+
 N))').  If @('N') is an explicit number (which is the case in the scenario we
 envision), this test will reduce (assuming the executable-counterparts of
 @(tsee ZP) and @(tsee BINARY-+) are @(see enable)d) to @('t') or to @('nil').
 In fact, the lemmas above (not including the lemma
 @('nthcdr-add1-conditional')) suffice to prove our goal:</p>

 @({
  (thm (let ((x (list x0 x1 x2 x3)))
         (equal (nthcdr (length x) (append x y))
                y))
       :hints (("Goal" :bdd (:vars nil))))
 })

 <p>If we execute the following form that disables the definition and
 executable-counterpart of the function @(tsee ZP)</p>

 @({
  (in-theory (disable zp (zp)))
 })

 <p>before attempting the proof of the theorem above, we can see more clearly
 the point of using @('IF*').  In this case, the prover makes the following
 report.</p>

 @({
  ACL2 Error in ( THM ...):  Unable to resolve test of IF* for term

  (IF* (ZP (+ 1 N)) X (NTHCDR N (CDR X)))

  under the bindings

  ((X (CONS X0 (CONS X1 (CONS X2 #)))) (N '3))

  -- use SHOW-BDD to see a backtrace.
 })

 <p>If we follow the advice above, we can see rather clearly what happened.
 See @(see show-bdd).</p>

 @({
  ACL2 !>(show-bdd)

  BDD computation on Goal yielded 21 nodes.
  ------------------------------

  BDD computation was aborted on Goal, and hence there is no
  falsifying assignment that can be constructed.  Here is a backtrace
  of calls, starting with the top-level call and ending with the one
  that led to the abort.  See :DOC show-bdd.

  (LET ((X (LIST X0 X1 X2 X3)))
       (EQUAL (NTHCDR (LENGTH X) (APPEND X Y)) Y))
    alist: ((Y Y) (X3 X3) (X2 X2) (X1 X1) (X0 X0))

  (NTHCDR (LENGTH X) (APPEND X Y))
    alist: ((X (LIST X0 X1 X2 X3)) (Y Y))

  (IF* (ZP (+ 1 N)) X (NTHCDR N (CDR X)))
    alist: ((X (LIST* X0 X1 X2 X3 Y)) (N 3))
  ACL2 !>
 })

 <p>Each of these term-alist pairs led to the next, and the test of the last
 one, namely @('(ZP (+ 1 N))') where @('N') is bound to @('3'), was not
 simplified to @('t') or to @('nil').</p>

 <p>What would have happened if we had used @(tsee IF) in place of @('IF*') in
 the rule @('nthcdr-add1')?  In that case, if @('ZP') and its @(see
 executable-counterpart) were disabled then we would be put into an infinite
 loop!  For, each time a term of the form @('(NTHCDR k V)') is encountered by
 the BDD package (where k is an explicit number), it will be rewritten in terms
 of @('(NTHCDR k-1 (CDR V))').  We would prefer that if for some reason the
 term @('(ZP (+ 1 N))') cannot be decided to be @('t') or to be @('nil'), then
 the BDD computation should simply abort.</p>

 <p>Even if there were no infinite loop, this kind of use of @('IF*') is useful
 in order to provide feedback of the form shown above whenever the test of an
 @('IF') term fails to simplify to @('t') or to @('nil').</p>")

(defxdoc iff
  :parents (basics acl2-built-ins)
  :short "Logical ``if and only if''"
  :long "<p>@('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')).</p>

 @(def iff)")

(defxdoc ifix
  :parents (numbers acl2-built-ins)
  :short "Coerce to an integer"
  :long "<p>@('Ifix') simply returns any integer argument unchanged, returning
 @('0') on a non-integer argument.  Also see @(see nfix), see @(see rfix), see
 @(see realfix) and see @(see fix) for analogous functions that coerce to a
 natural number, a rational number, a real, and a number, respectively.</p>

 <p>@('Ifix') has a @(see guard) of @('t').</p>

 @(def ifix)")

(defxdoc ignored-attachment
  :parents (defattach defconst defmacro defpkg)
  :short "Why attachments are sometimes not used"
  :long "<p>Attachments provide a way to execute constrained functions.  But in
 some cases, ACL2 will not permit such execution.  We discuss this issue
 briefly here.  For more information about attachments, see @(see
 defattach).</p>

 <p>We illustrate this issue with the following example, discussed below.</p>

 @({
    (encapsulate
     ()
     (defstub foo () t)
     (defn foo-impl-1 () t)
     (defattach foo foo-impl-1)
     (defn foo-impl-2 () nil)
     (local (defattach foo foo-impl-2))
     (defmacro mac () (foo)) ; nil in the first pass, t in the second pass
     (defun bar () (mac))    ; nil in the first pass, t in the second pass
     (defthm bar-is-nil
       (equal (bar) nil))
     )
 })

 <p>Here, a non-executable function @('foo') is introduced with no constraints,
 and is provided two contradictory implementations, @('foo-impl-1') and
 @('foo-impl-2').  A function, @('bar'), is defined using a macro, @('mac'),
 whose expansion depends on which of @('foo-impl-1') or @('foo-impl-2') is
 attached to @('foo').  If ACL2 were to allow this, then as indicated by the
 comments above, @('(bar)') would be defined to be @('nil') on the first pass
 of the @(tsee encapsulate) form, where @('foo') is attached to
 @('foo-impl-2'); but @('(bar)') would be defined to be @('t') on the second
 pass, where @('foo') is attached to @('foo-impl-1') because the second @(tsee
 defattach) call is @(tsee local).  Thus, after execution of the
 @('encapsulate') form, @('(bar)') would be provably equal to @('t') even
 though there would be a theorem, @('bar-is-nil') &mdash; proved during the
 first pass of the @('encapsulate') &mdash; saying that @('(bar)') is
 @('nil')!</p>

 <p>Fortunately, ACL2 does not permit this to happen.  The example above
 produces the following output.</p>

 @({
    ACL2 !>>(DEFUN BAR NIL (MAC))

    ACL2 Error in ( DEFUN BAR ...):  In the attempt to macroexpand the
    form (MAC), evaluation of the macro body caused the following error:

    ACL2 cannot ev the call of undefined function FOO on argument list:

    NIL

    Note that because of logical considerations, attachments (including
    FOO-IMPL-2) must not be called in this context.
 })

 <p>We see, then, the importance of disallowing evaluation using attachments
 during macroexpansion.  ACL2 is careful to avoid attachments in situations,
 like this one, where using attachments could be unsound.</p>

 <p>We conclude with an example illustrating how @(tsee make-event) can be used
 to work around the refusal of ACL2 to use attachments during macroexpansion.
 The idea is that @(tsee make-event) expansions are stored, and this avoids the
 issue of @(tsee local) attachments.  In particular, for the example below, the
 second @(tsee defattach) affects the body of @('f2') even though that @(tsee
 defattach) is @(tsee local), because the expansion of the corresponding @(tsee
 make-event) is saved during the first pass of @(tsee certify-book), when full
 admissibility checks are done.  Then even after including the book, the
 definition of @('f2') will be based on the second (@(tsee local)) @(tsee
 defattach) form below.</p>

 @({
  (in-package "ACL2")

  (defun body-1 (name formals body)
    (declare (ignore name))
    `(if (consp ,(car formals))
         ,body
       nil))

  (defun body-2 (name formals body)
    (declare (ignore name))
    `(if (acl2-numberp ,(car formals))
         ,body
       t))

  (defmacro defun+ (name formals body)
    `(make-event
      (if (foo) ; attachable stub
          '(defun ,name ,formals ,(body-1 name formals body))
        '(defun ,name ,formals ,(body-2 name formals body)))))

  ;;; (defun+ f1 (x y) (cons x y)) ; fails because foo has no attachment

  (defstub foo () t)
  (defn foo-true () t)
  (defn foo-false () nil)

  (defattach foo foo-true)

  (defun+ f1 (x y) (cons x y))

  (local (defattach foo foo-false))

  (defun+ f2 (x y) (cons x y))

  (assert-event (equal (f1 3 t) nil))

  (assert-event (equal (f2 3 t) (cons 3 t)))
 })")

(defxdoc ilk
  :parents (apply$)
  :short "Indicator of how an argument is used"
  :long "<p>The <i>ilk</i> of the ith argument of a @(tsee badge)d function
  symbol @('fn') is one of three tokens with the following meanings.</p>

  <ul>

  <li>@(':FN') - the ith argument is used exclusively as a function object by
  @('fn'); informally this means that the argument is passed only into slots of
  ilk @(':FN') in the definition of @('fn') and that on some (syntactic)
  execution paths reaches the first argument of a call of @(tsee apply$).</li>

  <li>@(':EXPR') - the ith argument is used exclusively as a expression object
  by @('fn'); informally this means that the argument is passed only into slots
  of ilk @(':EXPR') in the definition of @('fn') and that on some (syntactic)
  execution paths reaches the first argument of a call of @(tsee ev$).</li>

  <li>@('NIL') - the ith argument is never used as a function or expression
  object in the definition of @('fn').</li>

  </ul>

  <p>See @(tsee badge) for more details.</p>

  <p>The <i>ilks</i> of all the arguments of @('fn') are stored in the @(tsee
  badge) of @('fn').  If each ilk of @('fn') is @('NIL') the @(tsee badge)
  stores a @('T') as the ``list'' of ilks.</p>

  <p>The @(tsee badge) of @('fn') is computed by a successful call of @(tsee
  defwarrant) on @('fn').</p>

  <p>Ilks are used by the various notions of @(see tame)ness controlling
  whether @(tsee apply$) and @(tsee ev$) can properly interpret a quoted
  function or expression object.</p>")

(defxdoc illegal
  :parents (errors acl2-built-ins)
  :short "Print an error message and stop execution"
  :long "<p>@('(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 @(tsee fmt).  See @(see fmt), and see @(see prog2$) for an example
 of how to use a related function, @(tsee hard-error)
 (see @(see hard-error)).  Also see @(see er) for a macro that provides a
 unified way of signaling errors.</p>

 <p>The difference between @('illegal') and @(tsee hard-error) is that the
 former has a guard of @('nil') while the latter has a @(tsee guard) of @('t').
 Thus, you may want to use @('illegal') rather than @('hard-error') when you
 intend to do @(tsee guard) verification at some point, and you expect the
 guard to guarantee that the @('illegal') call is never executed.  See @(see
 prog2$) for an example.</p>

 <p>Technical note for raw Lisp programmers only: It is possible to cause hard
 errors to signal actual raw Lisp errors.  See @(see hard-error).</p>

 @(def illegal)")

(defxdoc illegal-state
  :parents (defabsstobj)
  :short "Illegal ACL2 state"
  :long "<p>See @(see set-absstobj-debug) for background on invariance
 violations for abstract @(see stobj)s.  In short, they may occur when
 execution does not complete for certain atomic operations.</p>

 <p>Such violations cause the following error message to be printed.</p>

 @({
 ACL2 Error in CHK-ABSSTOBJ-INVARIANTS:  Possible invariance violation
 for an abstract stobj!
 **PROCEED AT YOUR OWN RISK.**
 To proceed, evaluate the following form.
 :CONTINUE-FROM-ILLEGAL-STATE
 See :DOC set-absstobj-debug.
 })

 <p>At this point, the only way to get ACL2 to evaluate further input is to
 submit the form @(':CONTINUE-FROM-ILLEGAL-STATE'), as noted above &mdash; or
 more generally, the form it actually represents,
 @('(CONTINUE-FROM-ILLEGAL-STATE)'), which may need to be written as
 @('(ACL2::CONTINUE-FROM-ILLEGAL-STATE)') if the @(tsee current-package) is
 other than @('"ACL2"').  There is actually one exception: @(':')@(tsee q) is
 accepted, to pop out of the current call of @(tsee ld).</p>

 <p>To get a bit more information from the error message displayed above, see
 @(see set-absstobj-debug).</p>

 <p>See @(see community-book) file
 @('books/system/tests/abstract-stobj-nesting/nested-abstract-stobjs-input.lsp'),
 Examples 3 and 4, for relevant examples.</p>

 <p>Technical note.  An illegal-state is entered when ACL2 sets the @('ld')
 special, @(tsee ld-pre-eval-print), to the value @(':illegal-state').</p>")

(defxdoc imagpart
  :parents (numbers acl2-built-ins)
  :short "Imaginary part of a complex number"
  :long "<p>Completion Axiom (@('completion-of-imagpart')):</p>

 @({
  (equal (imagpart x)
         (if (acl2-numberp x)
             (imagpart x)
           0))
 })

 <p>@(see Guard) for @('(imagpart x)'):</p>

 @({
  (acl2-numberp x)
 })")

(defxdoc immediate-force-modep
  :parents (force)
  :short "When the @(see executable-counterpart) is @(see enable)d,
 @(see force)d hypotheses are attacked immediately"
  :long "<p>Also see @(see disable-immediate-force-modep) and see @(see
 enable-immediate-force-modep).</p>

 <p>This function symbol is defined simply to provide a @(see rune) which can
 be @(see enable)d and @(see disable)d.  Enabling</p>

 @({
  (:executable-counterpart immediate-force-modep)
 })

 <p>causes ACL2 to attack @(see force)d hypotheses immediately instead of
 delaying them to the next forcing round.</p>

 @({
  Example Hints
  :in-theory (disable (:executable-counterpart immediate-force-modep))
             ; delay forced hyps to forcing round
  :in-theory (enable (:executable-counterpart immediate-force-modep))
             ; split on forced hyps immediately
 })

 <p>See @(see force) for background information.  When a @(tsee force)d
 hypothesis cannot be established a record is made of that fact and the proof
 continues.  When the proof succeeds a ``forcing round'' is undertaken in which
 the system attempts to prove each of the @(see force)d hypotheses explicitly.
 However, if the @(see rune) @('(:executable-counterpart
 immediate-force-modep)') is @(see enable)d at the time the hypothesis is @(see
 force)d, then ACL2 does not delay the attempt to prove that hypothesis but
 undertakes the attempt more or less immediately.</p>")

(defxdoc implies
  :parents (basics acl2-built-ins)
  :short "Logical implication"
  :long "<p>@('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')).</p>

 @(def implies)")

(defxdoc improper-consp
  :parents (lists acl2-built-ins)
  :short "Recognizer for improper (non-@('nil')-terminated) non-empty lists"
  :long "<p>@('Improper-consp') is the function that checks whether its
 argument is a non-empty list that ends in other than @('nil').  See @(see
 proper-consp) and also see @(see true-listp).</p>

 @(def improper-consp)")

(defxdoc in-arithmetic-theory
  :parents (events)
  :short "Designate theory for some rewriting done for non-linear arithmetic"
  :long "<p>We assume familiarity with @(see theories); in particular, see
 @(see in-theory) for the normal way to set the current theory.  Here, we
 discuss an analogous event that pertains only to non-linear arithmetic
 (see @(see non-linear-arithmetic)).</p>

 @({
  Example:
  (in-arithmetic-theory '(lemma1 lemma2))

  General Form:
  (in-arithmetic-theory term)
 })

 <p>where @('term') is a term that when evaluated will produce a theory (see
 @(see theories)).  Except for the variable @(tsee world), @('term') must
 contain no free variables.  @('Term') is evaluated with the variable @(tsee
 world) bound to the current @(see world) to obtain a theory and the
 corresponding runic theory (see @(see theories)) is then used by non-linear
 arithmetic (see @(see non-linear-arithmetic)).</p>

 <p>Warning: If @('term') involves macros such as @(tsee ENABLE) and @(tsee
 DISABLE) you will probably not get what you expect!  Those macros are defined
 relative to the @(tsee CURRENT-THEORY).  But in this context you might wish
 they were defined in terms of the ``@('CURRENT-ARITHMETIC-THEORY')'' which is
 not actually a defined function.  We do not anticipate that users will
 repeatedly modify the arithmetic theory.  We expect @('term') most often to be
 a constant list of runes and so have not provided ``arithmetic theory
 manipulation functions'' analogous to @(tsee CURRENT-THEORY) and @(tsee
 ENABLE).</p>

 <p>See @(see non-linear-arithmetic).</p>")

(defxdoc in-package
  :parents (packages acl2-built-ins)
  :short "Select current package"
  :long "@({
  Example:
  (in-package "MY-PKG")

  General Form:
  (in-package str)
 })

 <p>where @('str') is a string that names an existing ACL2 package, i.e., one
 of the initial packages such as @('"KEYWORD"') or @('"ACL2"') or a package
 introduced with @(tsee defpkg).  For a complete list of the known packages
 created with @(tsee defpkg), evaluate</p>

 @({
  (strip-cars (known-package-alist state)).
 })

 <p>See @(see defpkg).  An ACL2 book (see @(see books)) must contain a single
 @('in-package') form, which must be the first form in that book.</p>")

(defxdoc in-tau-intervalp
  :parents (tau-system acl2-built-ins)
  :short "Boolean membership in a tau interval"
  :long "@({
  General Form:
  (in-tau-intervalp e x)
 })

 <p>Here, @('x') should be an interval (see @(tsee tau-intervalp)).  This
 function returns @('t') or @('nil') indicating whether @('e'), which is
 generally but not necessarily a number, is an element of interval @('x').  By
 that is meant that @('e') satisfies the domain predicate of the interval and
 lies between the two bounds.</p>

 <p>Suppose @('x') is an interval with the components <i>dom</i>,
 <i>lo-rel</i>, <i>lo</i>, <i>hi-rel</i> and <i>hi</i>.  Suppose @('(<?
 ')<i>rel u v</i>@(')') means @('(< ')<i>u v</i>@(')') when <i>rel</i> is true
 and @('(<= ')<i>u v</i>@(')') otherwise, with appropriate treatment of
 infinities.</p>

 <p>Then for @('e') to be in interval @('x'), it must be the case that @('e')
 satisfies the domain predicate <i>dom</i> (where where <i>dom</i>=@('nil')
 means there is no restriction on the domain) and @('(<? ')<i>lo-rel lo</i>@('
 e)') and @('(<? ')<i>hi-rel</i>@(' e ')<i>hi</i>@(')').  [Note: ``Appropriate
 treatment of infinities'' is slightly awkward if both infinities are
 represented by the same object, @('nil').  However, this is handled by
 coercing @('e') to a number <i>after</i> checking that it is in the domain.
 By this trick, ``@('<?')''  is presented with at most one ``infinity'' and it
 is always negative when in the first argument and positive when in the
 second.]</p>

 <p>Note that every element in an @('INTEGERP') interval is contained in the
 analogous @('RATIONALP') interval (i.e., the interval obtained by just
 replacing the domain @('INTEGERP') by @('RATIONALP')).  That is because every
 integer is a rational.  Similarly, every rational is an ACL2 number.</p>

 <p>Note that an interval in which the relations are weak and the bounds are
 equal rationals is the ``unit'' or ``identity'' interval containing exactly
 that rational.</p>

 <p>Note that an interval in which the relations are strong and the bounds are
 equal rationals is empty: it contains no objects.</p>

 <p>Note that the interval @('(make-tau-interval nil nil nil nil nil)') is the
 ``universal interval:'' it contains all ACL2 objects.  It contains all numbers
 because they satisfy the non-existent domain restriction and lie between
 minus infinity and plus infinity.  It contains all non-numbers because the
 interval contains @('0') and ACL2's inequalities coerce non-numbers to @('0').
 The universal interval is useful if you are defining a bounder (see @(see
 bounders)) for a function and do not wish to address a certain case: return
 the universal interval.</p>

 <p>Recall that @(tsee make-tau-interval) constructs intervals.  Using
 @('make-tau-interval') we give several self-explanatory examples of
 @('in-tau-intervalp'):</p>

 @({
  (in-tau-intervalp 3 (make-tau-interval 'INTEGERP nil 0 nil 10))           = t
  (in-tau-intervalp 3 (make-tau-interval 'RATIONALP nil 0 nil 10))          = t
  (in-tau-intervalp 3 (make-tau-interval NIL nil 0 nil 10))                 = t

  (in-tau-intervalp -3 (make-tau-interval 'INTEGERP nil 0 nil 10))          = nil
  (in-tau-intervalp 30 (make-tau-interval 'INTEGERP nil 0 nil 10))          = nil

  (in-tau-intervalp 3/5 (make-tau-interval 'INTEGERP nil 0 nil 10))         = nil
  (in-tau-intervalp 3/5 (make-tau-interval 'RATIONALP nil 0 nil 10))        = t

  (in-tau-intervalp #c(3 5) (make-tau-interval 'RATIONALP nil 0 nil 10))    = nil
  (in-tau-intervalp #c(3 5) (make-tau-interval 'ACL2-NUMBERP nil 0 nil 10)) = t

  (in-tau-intervalp 'ABC (make-tau-interval NIL nil 0 nil 10))              = t
 })")

(defxdoc in-theory
  :parents (events theories)
  :short "Designate ``current'' theory (enabling its rules)"
  :long "@({
  Example:
  (in-theory (set-difference-theories
               (universal-theory :here)
               '(flatten (:executable-counterpart flatten))))

  General Form:
  (in-theory term)
 })

 <p>where @('term') is a term that when evaluated will produce a theory (see
 @(see theories)).</p>

 <p>Except for the variable @(tsee world), @('term') must contain no free
 variables.  @('Term') is evaluated with the variable @(tsee world) bound to
 the current @(see world) to obtain a theory and the corresponding runic theory
 (see @(see theories)) is then made the current theory.  Thus, immediately
 after the @('in-theory'), a rule is @(see enable)d iff its rule name is a
 member of the runic interpretation (see @(see theories)) of some member of the
 value of @('term').  See @(see theory-functions) for a list of the commonly
 used theory manipulation functions.</p>

 <p>Note that it is often useful to surround @('in-theory') @(see events) with
 @('local'), that is, to use @('(local (in-theory ...))').  This use of @(tsee
 local) in @(tsee encapsulate) events and @(see books) will prevent the effect
 of this theory change from being exported outside the context of that
 @('encapsulate') or book.</p>

 <p>Also see @(see hints) for a discussion of the @(':in-theory') hint,
 including some explanation of the important point that an @(':in-theory') hint
 will always be evaluated relative to the current ACL2 logical @(see world),
 not relative to the theory of a previous goal.</p>

 <p>@(tsee In-theory) returns an @(see error-triple).  When the return is
 without error, the value is of the form @('(mv nil
 (:NUMBER-OF-ENABLED-RUNES k) state)') where @('k') is the length of the new
 current theory.  This value of @('k') is what is printed when an
 @('in-theory') event evaluates without error at the top level.</p>")

(defxdoc include-book
  :parents (books-reference books-tour events)
  :short "Load the @(see events) in a file"
  :long "@({
  Examples:

  ; Include using relative pathnames:
  (include-book "my-arith")
  (include-book "/../../my-arith")

  ; Include using absolute pathname:
  (include-book "/home/smith/my-arith")

  ; Include a community book:
  (include-book "arithmetic/top-with-meta" :dir :system)

  ; Include a project book:
  (include-book "my-subdir/my-book" :dir :my-project)

  General Form:
  (include-book file :load-compiled-file action
                     :uncertified-okp t/nil/:ignore-certs  ; [default t]
                     :defaxioms-okp t/nil                  ; [default t]
                     :skip-proofs-okp t/nil                ; [default t]
                     :ttags ttags                          ; [default nil]
                     :dir directory)
 })

 <p>where @('file') is a book-name without the @('".lisp"') extension.  See
 @(see books) for general information, see @(see book-name) for information
 about book-names, and see @(see pathname) for information about file names.
 @('Action') is one of @('t'), @('nil'), @(':default'), @(':warn'), or
 @(':comp'); these values are explained below, and the default is
 @(':default').  The three @('-okp') keyword arguments, which default to
 @('t'), determine whether errors or warnings are generated under certain
 conditions explained below; when the argument is @('t'), warnings are
 generated.  The @(':dir') argument, if supplied, is a keyword that represents
 an absolute @(see pathname) for a directory, to be used instead of the current
 book directory (see @(see cbd)) for resolving the given @('file') argument to
 an absolute pathname.  In particular, by default @(':dir :system') resolves
 the given @('file') using the @('books/') directory of your ACL2 installation;
 see ``Books Directory'' below.  To define other keywords that can be used with
 @(':dir'), see @(see add-include-book-dir), @(see add-include-book-dir!), and
 @(see project-dir-alist).  If the book has no @(see certificate), if its
 certificate is invalid (say, because its @(see book-hash) shows that books
 have changed after their certification), or if the certificate was produced by
 a different @(see version) of ACL2, a warning is printed and the book is
 included anyway; see @(see certificate).  This can lead to serious errors,
 perhaps mitigated by the presence of a @('.port') file from an earlier
 certification; see @(see uncertified-books).  If the portcullis of the @(see
 certificate) (see @(see portcullis)) cannot be raised in the host logical
 @(see world), an error is caused and no change occurs to the logic.
 Otherwise, the non-@(tsee local) @(see events) in file are assumed.  Then the
 @(see keep) of the @(see certificate) is checked to ensure that the correct
 files were read; see @(see keep).  A warning is printed if uncertified @(see
 books) were included.  Even if no warning is printed, @('include-book') places
 a burden on you; see @(see certificate).</p>

 <p>If you use @(see guard)s, please note @('include-book') is executed as
 though @('(set-guard-checking t)') has been evaluated; see @(see
 set-guard-checking).  If you want to run with different guard-checking,
 consider using @('ld') instead, or in addition; see @(see ld).</p>

 <p>The value of @(':load-compiled-file') controls whether a compiled file for
 the given @('file') is loaded by @('include-book').  Note that this keyword
 applies only to the given @('file'), not to any included sub-books.  In order
 to skip loading all compiled files, for the given @('file') as well as all
 included sub-books &mdash; for example, to avoid Lisp errors such as ``Wrong
 FASL version'' &mdash; use @('(set-compiler-enabled nil state)'); see @(see
 compilation).  Otherwise, if keyword argument @(':load-compiled-file') is
 missing or its value is the keyword @(':default'), then it is treated as
 @(':warn').  If its value is @('nil'), no attempt is made to load the compiled
 file for the book provided.  In order to load the compiled file, it must be
 more recent than the book's @(see certificate) (except in raw mode, where it
 must be more recent than the book itself; see @(see set-raw-mode)).  For
 non-@('nil') values of @(':load-compiled-file') that do not result in a loaded
 compiled file, ACL2 proceeds as follows.  Note that a load of a compiled file
 or expansion file aborts partway through whenever an @(tsee include-book) form
 is encountered for which no suitable compiled or expansion file can be loaded.
 For much more detail, see @(see book-compiled-file).</p>

 <blockquote>

 <p>@('t'): Cause an error if the compiled file is not loaded.  This same
 requirement is imposed on every @(tsee include-book) form evaluated during the
 course of evaluation of the present @('include-book') form, except that for
 those subsidiary @('include-book')s that do not themselves specify
 @(':load-compiled-file t'), it suffices to load the expansion file (see @(see
 book-compiled-file)).</p>

 <p>@(':warn'): An attempt is made to load the compiled file, and a warning is
 printed if that load fails to run to completion.</p>

 <p>@(':comp'): A compiled file is loaded as with value @('t'), except that if
 a suitable ``expansion file'' exists but the compiled file does not, then the
 compiled file is first created.  See @(see
 book-compiled-file).</p></blockquote>

 <p>The three @('-okp') arguments, @(':uncertified-okp'), @('defaxioms-okp'),
 and @('skip-proofs-okp'), determine the system's behavior when the book or any
 sub-book is found to be uncertified, when the book or any sub-book is found to
 contain @(tsee defaxiom) events, and when the book or any sub-book is found to
 contain @(tsee skip-proofs) events, respectively.  All three default to
 @('t'), which means it is ``ok'' for the condition to arise.  In this case, a
 warning is printed but the processing to load the book is allowed to proceed.
 When one of these arguments is @('nil') and the corresponding condition
 arises, an error is signaled and processing is aborted.  <b>Exceptions</b>:
 @(':uncertified-okp t') is ignored if the @('include-book') is being performed
 on behalf of a @(tsee certify-book), and @(':uncertified-okp :ignore-certs')
 is an advanced option explained later in this topic.</p>

 <p>The keyword argument @(':ttags') may normally be omitted.  A few
 constructs, used for example if you are building your own system based on
 ACL2, may require it.  See @(see defttag) for an explanation of this
 argument.</p>

 <p>@('Include-book') is similar in spirit to @(tsee encapsulate) in that it is
 a single event that ``contains'' other @(see events), in this case the @(see
 events) listed in the file named.  @('Include-book') processes the non-@(tsee
 local) event forms in the file, assuming that each is admissible.  @(tsee
 Local) @(see events) in the file are ignored.  You may use @('include-book')
 to load several @(see books), creating the logical @(see world) that contains
 the definitions and theorems of all of them.</p>

 <p>If any non-@(tsee local) event of the book attempts to define a @(see name)
 that has already been defined &mdash; and the book's definition is not
 syntactically identical to the existing definition &mdash; the attempt to
 include the book fails, an error message is printed, and no change to the
 logical @(see world) occurs.  See @(see redundant-events) for the details.</p>

 <p>When a book is included, the default @(see defun-mode) (see @(see
 default-defun-mode)) for the first event is always @(':')@(tsee logic).  That
 is, the default @(see defun-mode) ``outside'' the book &mdash; in the
 environment in which @('include-book') was called &mdash; is irrelevant to the
 book.  @(see Events) that change the @(see defun-mode) are permitted within a
 book (provided they are not in @(tsee local) forms).  However, such changes
 within a book are not exported, i.e., at the conclusion of an
 @('include-book'), the ``outside'' default @(see defun-mode) is always the
 same as it was before the @('include-book').</p>

 <p>Unlike every other event in ACL2, @('include-book') puts a burden on you.
 Used improperly, @('include-book') can be unsound in the sense that it can
 create an inconsistent extension of a consistent logical @(see world).  A
 certification mechanism is available to help you carry this burden &mdash; but
 it must be understood up front that even certification is no guarantee against
 inconsistency here.  The fundamental problem is one of file system security.
 See @(see certificate) for a discussion of the security issues.</p>

 <p>At the beginning of execution of an @('include-book') form, even before
 executing @(see portcullis) @(see command)s, the value of @(tsee
 acl2-defaults-table) is restored to the value it had at startup.  After
 execution of an @('include-book') form, the value of @(tsee
 acl2-defaults-table) is restored to what it was immediately before that
 @('include-book') form was executed.  See @(see acl2-defaults-table).</p>

 <p>An advanced option is @(':uncertified-okp :ignore-certs').  This tells ACL2
 to ignore all @(see certificate) files while including the book and its
 sub-books, thus treating all these books as uncertified.  This option may be
 useful when writing a @('.acl2x') file for the first ``run'' of a ``two-runs
 approach'' to certification; see @(see set-write-acl2x).  Note however that
 ordinary certification (the second ``run'') will then fail unless care is
 taken to avoid @(':uncertified-okp :ignore-certs') during that second
 certification run.  Finally (and speaking in general, not particularly about a
 @(tsee certify-book) context), we emphasize that the option
 @(':uncertified-okp :ignore-certs') applies when including all sub-books, not
 only for the current book.  In particular, a subsidiary @('include-book') call
 specifying @(':uncertified-okp nil') will fail, because the superior
 @(':ignore-certs') value causes the subsidiary book to be treated as
 uncertified, which conflicts with the requirement of @(':uncertified-okp
 nil').</p>

 <p><b>Books Directory.</b> We refer to the ``books directory'' of an
 executable image as the full pathname string of the directory associated with
 @('include-book') keyword option @(':dir :system') for that image.  By
 default, it is the @('books/') subdirectory of the directory where the sources
 reside and the executable image is thus built).  If those books reside
 elsewhere, the environment variable @('ACL2_SYSTEM_BOOKS') can be set to the
 directory under which they reside.  In most cases, your ACL2 executable is a
 small script in which you can set this environment variable just above the
 line on which the actual ACL2 image is invoked, for example:</p>

 @({
  export ACL2_SYSTEM_BOOKS
  ACL2_SYSTEM_BOOKS=/home/acl2/4-0/acl2-sources/books
 })

 <p>If you follow suggestions in the @(see installation) instructions, these
 books will be the ACL2 community books; see @(see community-books).  For
 another way to set the system books directory, which also permits similar
 handling for other directories, see @(see project-dir-alist).</p>

 <p>This concludes the guided tour through @(see books).  See @(see
 set-compile-fns) for a subtle point about the interaction between
 @('include-book') and on-the-fly @(see compilation).  See @(see certify-book)
 for a discussion of how to certify a book.</p>")

(defxdoc incompatible
  :parents (theories)
  :short "Declaring that two rules should not both be @(see enable)d"
  :long "@({
  Example:
  (theory-invariant (incompatible (:rewrite left-to-right)
                                  (:rewrite right-to-left)))

  General Form:
  (incompatible rune1 rune2)
 })

 <p>where @('rune1') and @('rune2') are two specific @(see rune)s.  The
 arguments are not evaluated.  @('Invariant') is just a macro that expands into
 a term that checks that not both @(see rune)s are enabled.  See @(see
 theory-invariant).  Also see @(see incompatible!) for a variant that insists
 the arguments are indeed runes, not merely having the shapes of runes.</p>")

(defxdoc incompatible!
  :parents (theories)
  :short "Declaring that two rules must exist and should not both be @(see enable)d"
  :long "<p>This variant of @('incompatible') causes an error if either of its
 arguments is not a @(see rune), by calling @(tsee active-or-non-runep) instead
 of @(tsee active-runep).  See @(see incompatible) and see @(see
 theory-invariant).</p>")

(defxdoc induction
  :parents (rule-classes)
  :short "Make a rule that suggests a certain induction"
  :long "@({
  Example:
  (defthm recursion-by-sub2-induction-rule
    t
    :rule-classes ((:induction :pattern (* 1/2 i)
                               :condition (and (integerp i) (>= i 0))
                               :scheme (recursion-by-sub2 i))))
 })

 <p>In ACL2, as in Nqthm, the functions in a conjecture ``suggest'' the
 inductions considered by the system.  Because every recursively defined
 function must be admitted with a justification in terms of a measure that
 decreases in a well-founded way on a given set of ``controlling'' arguments,
 every recursive definition suggests a dual induction scheme that ``unwinds''
 the function from a given application.  The case analysis in the induction
 scheme suggested by a function call is determined by the case analysis used to
 prove termination.  That case analysis chooses a subset of the tests governing
 recursive calls and then generates base cases for the combinations of tests
 that do not lead to recursive calls and induction steps for the combinations
 that do.  See @(see rulers) and @(see induction-coarse-v-fine-grained).</p>

 <p>For example, since @(tsee append) (actually @(tsee binary-append), but
 we'll ignore the distinction here) decomposes its first argument by successive
 @(tsee cdr)s as long as it is a cons, the induction scheme suggested by
 @('(append x y)') has a base case supposing @('x') to be an atom (i.e., not a
 cons) and then has an induction step in which the induction hypothesis is
 obtained by replacing @('x') by @('(cdr x)').  This substitution decreases the
 same measure used to justify the definition of @(tsee append).  Observe that
 an induction scheme is suggested by a recursive function application only if
 the controlling actuals are distinct variables, a condition that is sufficient
 to ensure that the ``substitution'' used to create the induction hypothesis is
 indeed a substitution and that it drives down a certain measure.  In
 particular, @('(append (foo x) y)') does not suggest an induction unwinding
 @(tsee append) because the induction scheme suggested by @('(append x y)')
 requires that we substitute @('(cdr x)') for @('x') and we cannot do that if
 @('x') is not a variable symbol.</p>

 <p>Once ACL2 has collected together all the suggested induction schemes it
 massages them in various ways, combining some to simultaneously unwind certain
 cliques of functions and vetoing others because they ``flaw'' others.  We do
 not further discuss the induction heuristics here; the interested reader
 should see @(see induction-heuristics).</p>

 <p>However, unlike Nqthm, ACL2 provides a means by which the user can
 elaborate the rules under which function applications suggest induction
 schemes.  Such rules are called @(':induction') rules.  The definitional
 principle automatically creates an @(':induction') rule, named @('(:induction
 fn)'), for each admitted recursive function, @('fn').  It is this rule that
 links applications of @('fn') to the induction scheme it suggests.  Disabling
 @('(:induction fn)') will prevent @('fn') from suggesting the induction scheme
 derived from its recursive definition (with an exception for induction schemes
 by way of user-defined induction rules, as discussed at the end below).  It is
 possible for the user to create additional @(':induction') rules by using the
 @(':induction') rule class in @(tsee defthm).</p>

 <p>Technically we are ``overloading'' @(tsee defthm) by using it in the
 creation of @(':induction') rules because no theorem need be proved to set up
 the heuristic link represented by an @(':induction') rule.  However, since
 @(tsee defthm) is generally used to create rules and rule-class objects are
 generally used to specify the exact form of each rule, we maintain that
 convention and introduce the notion of an @(':induction') rule.  An
 @(':induction') rule can be created from any lemma whatsoever.</p>

 @({
  General Form of an :induction Lemma or Corollary:
  T

  General Form of an :induction rule-class:
  (:induction :pattern pat-term
              :condition cond-term
              :scheme scheme-term)
 })

 <p>where @('pat-term'), @('cond-term'), and @('scheme-term') are all terms,
 @('pat-term') is the application of a function symbol, @('fn'),
 @('scheme-term') is the application of a function symbol, @('rec-fn'), that
 suggests an induction, and, finally, every free variable of @('cond-term') and
 @('scheme-term') is a free variable of @('pat-term').  We actually check that
 @('rec-fn') is either recursively defined &mdash; so that it suggests the
 induction that is intrinsic to its recursion &mdash; or else that another
 @(':induction') rule has been proved linking a call of @('rec-fn') as the
 @(':pattern') to some scheme.</p>

 <p>The induction rule created is used as follows.  When an instance of the
 @(':pattern') term occurs in a conjecture to be proved by induction and the
 corresponding instance of the @(':condition') term is known to be non-@('nil')
 (by @(see type-reasoning) alone), the corresponding instance of the
 @(':scheme') term is created and the rule ``suggests'' the induction, if any,
 suggested by that term.  (Analysis of that term may further involve induction
 rules, though the applied rule is removed from consideration during that
 further analysis, in order to avoid looping.)  If @('rec-fn') has a recursive
 definition, then the definition's dual induction scheme is suggested (i.e.,
 unwinding the function).</p>

 <p>(Remark.  Unlike @(':induct') @(see hints), the @(':scheme') of an
 @(':induction') rule only introduces induction schemes based on the top-level
 function symbol of the indicated term, not of any of its subterms.  End of
 Remark.)</p>

 <p>Consider, for example, the example given above,</p>

 @({
  (:induction :pattern (* 1/2 i)
              :condition (and (integerp i) (>= i 0))
              :scheme (recursion-by-sub2 i)).
 })

 <p>In this example, we imagine that @('recursion-by-sub2') is the
 function:</p>

 @({
  (defun recursion-by-sub2 (i)
    (if (and (integerp i)
             (< 1 i))
        (recursion-by-sub2 (- i 2))
        t))
 })

 <p>Observe that this function recursively decomposes its natural number
 argument by subtracting @('2') from it repeatedly and stops when the argument
 is @('1') or less.  The value of the function is irrelevant; it is its
 induction scheme that concerns us.  The induction scheme suggested by
 @('(recursion-by-sub2 i)') is</p>

 @({
  (and (implies (not (and (integerp i) (< 1 i)))   ; base case
                (:p i))
       (implies (and (and (integerp i) (< 1 i))    ; induction step
                     (:p (- i 2)))
                (:p i)))
 })

 <p>We can think of the base case as covering two situations.  The first is
 when @('i') is not an integer.  The second is when the integer @('i') is less
 than or equal to @('1').  In the base case we must prove @('(:p i)') without
 further help.  The induction step deals with those natural numbers @('i')
 greater than @('1'), and inductively assumes the conjecture for @('i-2') while
 proving it for @('i').  Let us call this scheme ``induction on @('i') by
 twos.''</p>

 <p>Suppose the above @(':induction') rule has been added.  Then an occurrence
 of, say, @('(* 1/2 k)') in a conjecture to be proved by induction would
 suggest, via this rule, an induction on @('k') by twos, provided @('k') was
 known to be a nonnegative integer.  This is because the induction rule's
 @(':pattern') is matched in the conjecture, its @(':condition') is satisfied,
 and the @(':scheme') suggested by the rule is that derived from
 @('(recursion-by-sub2 k)'), which is induction on @('k') by twos.  Similarly,
 the term @('(* 1/2 (length l))') would suggest no induction via this rule,
 even though the rule ``fires'' because it creates the @(':scheme')
 @('(recursion-by-sub2 (length l))') which suggests no inductions unwinding
 @('recursion-by-sub2') (since the controlling argument of
 @('recursion-by-sub2') in this @(':scheme') is not a variable symbol).</p>

 <p>Continuing this example one step further illustrates the utility of
 @(':induction') rules.  We could define the function @('recursion-by-cddr')
 that suggests the induction scheme decomposing its @(tsee consp) argument two
 @(tsee cdr)s at a time.  We could then add the @(':induction') rule linking
 @('(* 1/2 (length x))') to @('(recursion-by-cddr x)') and arrange for @('(*
 1/2 (length l))') to suggest induction on @('l') by @(tsee cddr).</p>

 <p>Observe that @(':induction') rules require no proofs to be done.  Such a
 rule is merely a heuristic link between the @(':pattern') term, which may
 occur in conjectures to be proved by induction, and the @(':scheme') term,
 from which an induction scheme may be derived.  Hence, when an @(':induction')
 rule-class is specified in a @(tsee defthm) event, the theorem proved is
 irrelevant.  The easiest theorem to prove is, of course, @('t').  Thus, we
 suggest that when an @(':induction') rule is to be created, the following form
 be used:</p>

 @({
  (defthm name T
    :rule-classes ((:induction :pattern pat-term
                               :condition cond-term
                               :scheme scheme-term)))
 })

 <p>The name of the rule created is @('(:induction name)').  When that @(see
 rune) is @(see disable)d the heuristic link between @('pat-term') and
 @('scheme-term') is broken.</p>

 <p>Note that if @('fn') is defined recursively and @('(:induction fn)') is
 @(see disable)d, then normally the induction scheme for @('fn') will not be
 available during a proof.  However, the induction scheme for @('fn') is
 available, even if it is disabled, when it is indicated by application of a
 user-defined @(':induction') rule.  So for the @(':induction') rule above,
 @('recursion-by-sub2-induction-rule'): even if @('(:induction
 recursion-by-sub2)') is disabled, nevertheless the induction scheme for
 @('recursion-by-sub2') will be available to apply to the instantiated
 @(':scheme-term').</p>")

(defxdoc induction-coarse-v-fine-grained
  :parents (rulers)
  :short "advice on case explosion in complex inductions"
  :long "<p>Recursive functions suggest inductions based on the case analysis
  in the function definition and the positions of recursive calls within that
  case analysis.  That analysis is done when termination is proved.  Key parts
  of that analysis are the notions of governing tests and ruling tests.  By
  using the so-called ``ruler-extenders'' feature of termination analysis you
  can sometimes choose between ``coarse-grained'' and ``fine-grained''
  inductions.  The former have few cases but may provide multiple and sometimes
  irrelevant induction hypotheses.  The latter provide more cases, each
  targeted at a given output, and tend to provide only induction hypotheses
  needed for that output.  See @(see rulers) for a discussion of
  ruler-extenders.</p>

  <h3>Governing versus Ruling Tests</h3>

  <p>Roughly speaking, a test <i>governs</i> a recursive call if the test must
  be true for control to reach that call.  The <i>ruling</i> tests are a subset
  of the governing tests and are the ones that determine the case analysis of
  any suggested induction.</p>

  <p>For example, if we are analyzing a definition of @('(fn x)') and the body
  is @('(if (not (consp x)) (h nil) (h (fn (cdr x))))') then @('(consp x)')
  governs the recursive call and it also rules the call.  But if the body were
  @('(h (if (not (consp x)) nil (fn (cdr x))))') then @('(consp x)') governs the
  recursive call but may not rule it.  It would be considered a ruler if the
  symbol @('h') were on the ``ruler-extenders'' list &mdash; the list of
  symbols that allow further collection of rulers from inside terms that begin
  with those symbols.</p>

  <p>The default setting of ruler-extenders is @('(if mv-list return-last)').
  That means that termination (and induction) analysis stops looking for ruling
  tests when a term is encountered that does not begin with one of these listed
  symbols.  For example, under the default ruler-extenders, when the analysis
  encounters a term that starts with a @('lambda') expression, that term is
  considered a tip of the tree.  (@('Lambda') expressions are relevant because
  they are introduced by the macroexpansion of @(tsee let) and @(tsee let*)
  expressions, which arise frequently in interesting recursive functions
  because they facilitate <i>code sharing</i> by allowing the computation of
  intermediate results used on multiple output branches.)  When the analysis
  encounters a term considered a tip, the rulers collected so far are used to
  rule <i>all</i> the recursive calls in that tip.  So at a tip, the analysis
  collects all the recursive calls occurring in that tip and forms measure
  conjectures and, eventually, induction hypotheses about them, using the
  rulers as the hypotheses of those conjectures.</p>

  <p>So the user can influence the determination of the rulers by setting the
  ``ruler-extenders'' in effect when the function is admitted.  The global
  default ruler-extenders can be set by the event @('set-ruler-extenders') or
  specified locally in a @('defun') by the @(tsee xargs) keyword
  @(':ruler-extenders').  See @(see rulers) for the details.</p>

  <h3>Coarse versus Fine Induction Case Analysis</h3>

  <p>Most often, users think about ruler-extenders only in the context of
  <i>failed</i> termination proofs: inspection of the measure conjectures
  reveal that an important governing hypothesis was curiously omitted, the user
  consults the documentation or appeals for help from other users, and is
  reminded of ruler-extenders.  One could argue that users forget about
  ruler-extenders because the default setting for ruler-extenders is so often
  the ``right'' one.  But sometimes even a function that is successfully
  admitted under the default setting would benefit from selecting a non-default
  setting for ruler-extenders.</p>

  <p>Sometimes you may feel that the prover is struggling with an induction
  suggested by a function, even though the function that suggested the
  induction is the one you expected to be selected, and for most simple
  recursive functions the induction suggested is the ``perfect'' induction for
  that function.  This problem of the prover struggling to simplify the
  induction steps might arise most commonly with functions that have @(tsee
  let*) bindings that contain @('if')-expressions, some of which contain
  recursive calls.  For example, the following artificial example raises the
  possibility of this problem.</p>

  @({
  (defun fn (x y)
    (if (consp x)
        (let* ((y1 (if (consp (car x))
                       (fn (car x) (cons 'car y))
                       y))
               (y2 (if (consp (cdr x))
                       (fn (cdr x) (cons 'cdr y1))
                       y1)))
          (cons y1 y2))
        y))
  })

  <p>Recall that @('let*') expressions are translated into nested @('lambda')
  expressions, so the formal definition of @('fn') is</p>

  @({
  (defun fn (x y)
    (if (consp x)
        ((lambda (y1 x)
           ((lambda (y2 y1) (cons y1 y2))
            (if (consp (cdr x))
                (fn (cdr x) (cons 'cdr y1))
              y1)
            y1))
         (if (consp (car x))
             (fn (car x) (cons 'car y))
           y)
         x)
        y))
  })

  <p>So, the entire @('let*') above, i.e., the formal term starting with the
  first @('lambda') expression, is a tip ruled only by @('(consp x)').  The
  @('if')s within it are not considered even though their tests govern (but do
  not rule) the subsequent recursions.  The recursive calls in that tip are</p>

  @({
  (fn (car x) (cons 'car y))
  })

  <p>and</p>

  @({
  (fn (cdr x)
      (cons 'cdr
            (if (consp (car x))
                (fn (car x) (cons 'car y))
                y))).
  })

  <p>The default measure in this definition is @('(acl2-count x)').  The
  measure conjectures are easy to prove because @('(consp x)') implies
  @('(acl2-count (car x))') and @('(acl2-count (cdr x))') are both less than
  @('(acl2-count x)').  Since there are no more recursive calls in the
  definition, @('fn') is admitted.</p>

  <p>Now consider how the prover would attempt to prove @('(p (fn x y))') by
  the induction suggested by @('fn').  The induction argument, shown below, has
  one base case and one induction step.  The induction step has two induction
  hypotheses.</p>

  @({
  (and (implies (not (consp x)) (p (fn x y)))
       (implies (and (consp x)
                     (p (fn (car x) (cons 'car y)))
                     (p (fn (cdr x)
                            (cons 'cdr
                                  (if (consp (car x))
                                      (fn (car x) (cons 'car y))
                                      y)))))
                (p (fn x y)))).
  })

  <p><b>Note</b>: Here and throughout this documentation topic we freely
  rearrange the formulas we display to make it easier to compare different
  induction schemes.  For example, when the prover attempts to prove @('(p (fn
  x y))') it lists the conjuncts above in the opposite order, i.e., the base
  case occurs last.  It can be hard to compare induction schemes from similar
  functions because ACL2's methods of generating induction schemes does not
  preserve the order of tips.</p>

  <p>The prover attempts to reduce each of these two conjuncts to @('T') by
  simplification.  The base case is generally simple.  So consider the
  induction step, the second implication above, which we abbreviate here as</p>

  <code>
  (implies (and (consp x)
                <i>ind-hyp1</i>
                <i>ind-hyp2</i>)
           <i>ind-concl</i>)
  </code>

  <p>where, <i>ind-hyp1</i>, the first induction hypothesis, is @('(p (fn (car
  x) (cons 'car y)))'), etc.  See @(see introduction-to-the-theorem-prover) for
  more details of how the rewriter works.  When rewriting the formula above it
  basically proceeds left-to-right, innermost first, keeping track of what can
  be assumed given the context in which terms occur.  Thus, by the time the
  rewriter gets to the induction conclusion, <i>ind-concl</i>, the two
  induction hypotheses will have been rewritten, making them easier to find and
  identify as true if they occur in the rewriting of the conclusion.</p>

  <p>But rewriting <i>ind-hyp1</i> here will involve rewriting @('(fn (car
  x) (cons 'car y))'), which is completely irrelevant to half of the proof of
  <i>ind-concl</i>.  In particular, inspection of @('fn') reveals that the
  first recursive call of @('fn') is only relevant if @('(consp (car x))') is
  true.  But we know nothing about @('(car x)') in this induction step.
  Furthermore, rewriting a call of a recursive function can be very expensive
  since it requires (a) rewriting the actual expressions, then (b) rewriting
  the body of the function under a substitution replacing the function's
  formals by the rewritten actuals, and then (c) heuristically deciding whether
  the rewritten body is preferable to the call, given the subterms occurring
  elsewhere in the goal.</p>

  <p>Another way to describe the unfortunate induction scheme above is that it
  ``coarse,'' because it provides a simple case analysis, which necessitates
  lumping all the possibly relevant induction hypotheses into a single case (in
  this particular example).  When the induction conclusion opens, after the
  induction hypotheses have all been simplified, it will cause further
  splitting, (e.g., on @('(consp (car x))')), and in some of those subgoals
  some of the simplified induction hypotheses will be irrelevant (but still
  burden the simplification process if the cases are not proved
  immediately).</p>

  <p>Depending on how hard it is to rewrite irrelevant induction hypotheses
  &mdash; which depends not just on the function, like @('fn'), suggesting the
  induction but also on the conjecture being proved &mdash; it might be more
  efficient to have a finer-grained case analysis so that the only induction
  hypotheses in a given case are those on a given execution path.</p>

  <p>A finer-grained induction scheme is generated, in the case of @('fn'), by
  arranging for @('lambda') expressions <i>not</i> to stop the collection of
  rulers.  This can be done by adding the keyword @(':lambdas') to the
  ruler-extenders.  The presence of that keyword means ``keep collecting rulers
  as you dive into <i>any</i> term beginning with a @('lambda') expression.''
  (By the way, normally @(':ruler-extenders') expects a list but if you specify
  the single keyword @(':lambdas') it denotes the list @('(if :lambdas mv-list
  return-last)').)  Again, see @('rulers') for details.</p>

  <p>If we had defined @('fn') as shown below we would get the finer induction
  analysis shown subsequently.</p>

  @({
  (defun fn (x y)
    (declare (xargs :ruler-extenders :lambdas))
    (if (consp x)
        (let* ((y1 (if (consp (car x))
                       (fn (car x) (cons 'car y))
                       y))
               (y2 (if (consp (cdr x))
                       (fn (cdr x) (cons 'cdr y1))
                       y1)))
          (cons y1 y2))
        y))
  })

  <p>Note that @('fn') can be admitted without extending the rulers &mdash; we
  have already demonstrated that.  We are including @(':lambdas') here
  precisely to get a finer case analysis for induction.</p>

  <p>The induction generated is shown below.  We have slightly simplified the
  induction by replacing @('(if ')<i>a b c</i>@(')') by <i>b</i> when <i>a</i>
  is among the hypotheses in the case analysis, and by replacing @('(if ')<i>a
  b c</i>@(')') by <i>c</i> when @('(not ')<i>a</i>@(')') is among the
  hypotheses.  This simplification is actually not done by induction analysis
  but by the first simplification.</p>

  @({
  (and (implies (not (consp x)) (p (fn x y)))
       (implies (and (consp x)
                     (not (consp (car x)))
                     (not (consp (cdr x))))
                (p (fn x y)))
       (implies (and (consp x)
                     (not (consp (car x)))
                     (consp (cdr x))
                     (p (fn (cdr x) (cons 'cdr y))))
                (p (fn x y)))
       (implies (and (consp x)
                     (consp (car x))
                     (not (consp (cdr x)))
                     (p (fn (car x) (cons 'car y))))
                (p (fn x y)))
       (implies (and (consp x)
                     (consp (car x))
                     (consp (cdr x))
                     (p (fn (car x) (cons 'car y)))
                     (p (fn (cdr x)
                            (cons 'cdr (fn (car x) (cons 'car y))))))
                (p (fn x y))))
  })

  <p>Note that the case analysis here steers the @('(fn x y)') in the
  conclusion down exactly one path and the only hypotheses provided in each
  induction step concern recursive calls on that path.</p>

  <p>The finer case analysis gives us two base cases and four induction steps,
  one of which has two induction hypotheses.  We'll encounter terms of the form
  @('(p (fn ...))') nine times in using this scheme, instead of just four such
  terms in the first scheme we showed.  It may seem surprising that this scheme
  ever leads to faster proofs than the earlier one.  But it can.  Whether it
  does depends, as mentioned above, on the complexity of rewriting the
  recursive calls involved and the conjecture being proved.</p>

  <p><b>Note</b>: The ruler-extenders may include arbitrary function symbols
  and the keyword @(':lambdas') as above.  But it can also be set to @(':all')
  which makes all the governors be rulers, i.e., collection of rulers dives
  through all function symbols.  We focus here on diving through @('lambda')
  expressions because they are by far the most common ``function
  symbol'' (other than @('if')) under which one finds additional tests and
  recursive calls.</p>

  <p>In the next section we'll discuss a theorem that makes use of these
  insights and demonstrates that the finer scheme can lead to faster
  proofs.</p>

  <h3>An Actual Example of Coarse versus Fine Induction Schemes</h3>

  <p>The ACL2 prettyprinter is implemented with the function @('ppr').  It is
  basically the composition of two functions, @('ppr1'), which takes the object
  to be printed and computes a ``ppr tuple'' describing how much to indent each
  subexpression and where to break the lines, and @('ppr2'), which actually
  prints.  To admit @('ppr') as a logic mode function we have to prove
  termination and verify the guards of all the functions involved.  To verify
  the guards, we have to prove that @('ppr1') returns a @('ppr-tuple-p').  You
  can see the definitions of @('ppr1') and @('ppr-tuple-p') and their mutually
  recursive peers by using the @(':')@(tsee pe) command, e.g., @(':pe
  ppr1').</p>

  <p>We'll focus here on @('ppr1'), which is mutually recursive with
  @('ppr1-lst').  To prove anything interesting about a function in a mutually
  recursive clique you generally have to simultaneously prove analogous
  theorems about every function in the clique.  That is most often done by
  defining a ``flagged'' function which can recur as any function in the clique
  according to a flag.  The community book @('books/tools/flag') provides a
  convenient way to do that.  Since that book facilitates the introduction of
  the flagged function, it allows the generated definition to be processed with a
  user-supplied ruler-extenders.</p>

  <p>A good demonstration of the ``coarse'' and ``fine'' induction schemes for
  @('ppr1') can be found in the community book
  @('books/demos/ppr1-experiments').  We summarize the contents of that book
  here.</p>

  <p>The book proves that @('ppr1') returns a @('ppr-tuple-p') and
  @('ppr1-lst') returns a @('ppr-tuple-lst-p').  In fact, it does that proof
  seven times, under coarse and fine inductions and variations on some hints.
  The coarse induction is obtained by admitting a flagged version of
  @('ppr1')/@('ppr1-lst') under the default ruler-extenders.  The fine
  induction is obtained by admitting a differently named flagged version of
  @('ppr1')/@('ppr1-lst') with @(':ruler-extenders :lambdas').</p>

  <p>The coarse induction, generated under the default ruler-extenders, has 76
  cases.  Six are base cases.  The other 70 are induction steps with varying
  numbers of induction hypotheses as given in the sketch below.</p>

  @({
  (76           ;; 76 cases in the induction scheme
      (0 . 6)   ;; no induction hyps in 6 cases, i.e., Base Cases
      (1 . 8)   ;; 1 induction hyp in 8 cases
      (2 . 2)   ;; 2 induction hyps in 2 cases
      (3 . 16)  ;; 3 induction hyps in 16 cases
      (4 . 32)  ;; 4 induction hyps in 32 cases
      (8 . 4)   ;; 8 induction hyps in 4 cases
      (9 . 8))  ;; 9 induction hyps in 8 cases
  })

  <p>The fine induction, generated under the @(':lambdas') ruler-extension, can
  be similarly sketched.</p>

  @({
  (256          ;; 256 cases in the induction scheme
      (0 . 6)   ;; no induction hyps in 6 cases, i.e., Base Cases
      (1 . 8)   ;; 1 induction hyp in 8 cases
      (2 . 82)  ;; 2 induction hyps in 82 cases
      (3 . 80)  ;; 3 induction hyps in 80 cases
      (4 . 80)) ;; 4 induction hyps in 80 cases
  })

  <p>The induction generated under the @(':all') ruler-extensions is identical
  to the fine induction for @('ppr1') and @('ppr1-lst').  (No governing
  @('if')s are hidden under function calls other than @('if') and @('lambda')
  expressions in those two functions.)</p>

  <p>Regardless of which induction scheme we use, the proof that @('ppr1')
  returns a @('ppr-tuple-p') and that @('ppr1-lst') returns a
  @('ppr1-tuple-lst-p') fails without a certain hint: we have to tell the
  prover to expand the calls of @('ppr1') and @('ppr1-lst') in the conclusions
  of the induction steps.  If you try to prove the theorem without the hint the
  first checkpoint makes clear that you need the hint.  (This is not an
  uncommon problem in inductive proofs about mutually recursive functions.)
  But in the most basic like-for-like comparison of the successful proof of the
  theorem by each induction scheme augmented by an @(':expand') hint, the
  coarse induction takes 2,165 seconds and the fine induction takes 65 seconds.
  See scenarios 1 and 3 in the next section.</p>

  <h3>Comparing Several Optimizations</h3>

  <p>After noticing the performance differences between the coarse and fine
  inductions we spent some time trying to further optimize the proof.  We
  compared seven different combinations of approaches.  We discuss them here.
  See the @('books/demos/ppr1-experiments') for the details of each hint, etc.
  The times reported below were originally recovered from the @('.cert.out')
  file after certification of the book in September, 2023, using the
  development copy of ACL2 slated to become Version  8.6, running in CCL on a
  Macbook Pro.  Inspect the @('.cert.out') file for more recent results.</p>

  <p>As mentioned previously, a common situation with inductive proofs about
  complicated mutually recursive functions is that the calls in the conclusion
  aren't always automatically opened by ACL2's heuristics.  So it is not
  unusual in such proofs to provide a hint that explicitly expands the
  @('ppr1') and @('ppr1-lst') calls in the conclusion.  In these experiments we
  provide that hint two ways, either as part of fairly sophisticated computed
  hint or with an @(':expand') hint on @('"Goal"').  If you try to prove this
  theorem with no hint it fails.</p>

  <p>We will also be experimenting with the enabled status of @('ppr1') and
  @('ppr1-lst').</p>

  <p>The seven scenarios are specified by saying which induction scheme is
  used, whether @('ppr1') and @('ppr1-lst') are enabled or disabled by default,
  and what hints are provided.  There are three basic hints to chose from.</p>

  <ul>

  <li>@('computed') &mdash; when a subgoal becomes stable, open @('ppr1') and
      @('ppr1-lst') in the conclusion, and when any subgoal of that becomes
      stable again, enable @('ppr1') and @('ppr1-lst') and let ACL2's
      heuristics take over.  This hint only makes sense if @('ppr1') and
      @('ppr1-lst') are initially disabled.</li>

  <li> @('computed'') &mdash; like @('computed') but skips the first stable
       opening of @('ppr1') and @('ppr1-lst').  That is handled instead by an
       @(':expand') hint.</li>

  <li>@(':expand') &mdash; a traditional @(':expand') hint to open @('ppr1')
      and @('ppr1-lst') terms as they appear in induction conclusions.
      The expand hint is
      @({
      :expand
      ((:free (print-base print-radix width rpc state eviscp)
              (ppr1 x print-base print-radix width rpc state eviscp))
       (:free (print-base print-radix width rpc pair-keywords-p state eviscp)
              (ppr1-lst lst print-base print-radix width rpc
                        pair-keywords-p state eviscp)))
      })
      which allows the non-controller arguments of @('ppr1') and @('ppr1-lst')
      to be any terms but insists that the controllers, @('x') and @('lst'),
      respectively, be those particular variable names.</li>

      </ul>

  <p>In addition, we sometimes avail ourselves of special-purpose lemmas.</p>

  <ul>
  <li>@('NIL lem')  &mdash; rewrites @('(ppr1-lst nil ...)') to @('nil').</li>

  <li>@('MAX hack') &mdash; lemmas about @('MAX') allowing us to disable @('MAX')</li>
  </ul>

  <p>We try seven different combinations, numbered 1-7, but listed below
  in descending order of proof times.</p>

  @({
  n      induction    status                 hints               proof time

  1       coarse      enabled      :expand                         2165.19
  2       coarse      disabled     computed                         207.49
  6       fine        disabled     computed                          82.29
  3       fine        enabled      :expand                           65.00
  4       fine        disabled     computed + :expand                62.86
  5       fine        disabled     computed' + :expand + NIL lem     61.58
  7       fine        disabled     computed + :expand + MAX hack     55.14
  })

  <p>Note that scenarios 1 and 3 are a direct comparison of coarse and fine
  induction with exactly the same hint.  The coarse induction took 2165.19
  seconds and the fine induction took 65.00, despite the fact that the coarse
  induction had 76 cases to deal with and the fine induction had 256.  The most
  likely reason the coarse induction performed poorly is that there were 8
  induction steps that had 9 induction hypotheses each, even though no case
  ever actually required more than 4 induction hypotheses.</p>

  <p>Scenario 2 shows that much time is saved by disabling @('ppr1') and
  @('ppr1-lst') and expanding them (when stable) with the computed hint.  Note
  that since the computed hint first expands them in the conclusion and lets
  the resulting subgoals stabilize before enabling @('ppr1') and @('ppr1-lst'),
  the calls of @('ppr1') and @('ppr1-lst') in the induction hypotheses do not
  expand until the relevant case analysis is exposed by expanding the
  conclusion.</p>

  <p>Scenarios 4, 5, 6, and 7, attempt to improve upon the time seen in
  scenario 3.  We see that the best performance in this particular problem is
  to use the fine induction case analysis, keep the relevant recursive
  functions disabled by default, use an @(':expand') hint to open them in the
  conclusion but also have a computed hint that expands them in the conclusions
  if a stable subgoal arises, and only enable those functions if they're still
  in the subsequently stable subgoals.  The @('MAX hack') saves another 10% by
  avoiding case splits caused by the many occurrences of @('MAX') in
  @('ppr1').</p>

  <p>However, it should be noted that the major source of improvement is the
  use of the fine induction scheme.  The fact that there is only a 10% further
  improvement achieved by the various other hints suggests it may not be worth
  the effort!  Coding the computed hint took time and thought, compared to just
  using an @(':expand') hint.  And it was a lot easier to leave @('ppr1') and
  @('ppr1-lst') enabled and let ACL2 decide when to expand them than it was to
  disable them and control their expansion by hints and lemmas.  One take-home
  lesson for us was that ACL2's heuristics for opening recursive functions are
  pretty good!</p>

  <p>Ignoring scenario 7 &mdash; where the additional improvement came from a
  completely different source, namely, avoiding the expansion of @('MAX')
  expressions &mdash; the difference between the easiest thing to do (scenario
  3) and the fastest method that focused on manually controlling @('ppr1') and
  @('ppr1-lst') (scenario 5) was less than 4 seconds.  So, as usual with all
  kinds of performance optimization, don't get sucked down the rabbit hole!
  Take the easy wins and get on with the rest of your project!</p>

  <h3>Conclusion</h3>

  <p>Of course, whether fine induction schemes will improve other proofs just
  depends on how many irrelevant induction hypotheses are present and how
  complicated it is to simplify the terms in the theorem.  If you are proving
  something about a recursive function that contains @('let*') expressions in
  which some of the bindings conditionally make recursive calls, be alert to
  the possibility that adjusting ruler-extenders to include @(':lambdas') may
  give better inductive performance.  If you witness the prover engaged in
  fairly deep case splits, even as it seems always to prove the resulting
  cases, you might look for ways to get a finer induction case analysis.</p>")

(defxdoc induction-depth-limit
  :parents (induction)
  :short "The maximum number permitted of nested inductions"
  :long "<p>ACL2 may limit the number of levels of induction.  Consider for
 example a subgoal with this @(see goal-spec):</p>

 @({
 Subgoal *1.2.3.1.2.3.1.2.3/7'11'
 })

 <p>This represents nine levels of induction.  By default, that is the maximum
 permitted, since proofs rarely succeed with more than a few levels of
 induction.  (Indeed, one is well served by relying on only one level of
 induction, avoiding nested inductions in favor of proving suitable @(see
 rewrite) rules.  See @(see the-method).)  Thus, if ACL2 would otherwise
 attempt to push the subgoal indicated above for later proof by induction, the
 overall proof would fail because that would cause the maximum nesting depth of
 9 to be exceeded.</p>

 <p>To see the current limit:</p>

 @({
 (induction-depth-limit (w state))
 })

 <p>This limit is always a natural number, with one exception: it can be
 @('nil'), which means that there is no limit on the nesting depth of
 inductions.</p>

 <p>Note that an explicit @(':induct') hint (see @(see hints)) will cause an
 induction to occur, regardless of the induction-depth-limit.  Of course, if
 we have already reached the induction-depth-limit at the point the
 @(':induct') hint is applied, then any attempt to push a subgoal for induction
 will fail (unless it too has an associated @(':induct') hint).</p>

 <p>To change the limit, see @(see set-induction-depth-limit).</p>

 <p>For another way to limit the lengths of proof attempts, see @(tsee
 set-subgoal-loop-limits).</p>")

(defxdoc induction-heuristics
  :parents (rule-classes)
  :short "How ACL2 selects induction schemes"
  :long "<p>This topic is for those curious about induction heuristics in ACL2.
 It is not necessary to understand those heuristics to be able to use ACL2
 successfully.</p>

 <p>ACL2's heuristics for generating an induction scheme for a conjecture are
 very similar to Nqthm's and can trace their roots all the way back to the
 Edinburgh Pure Lisp Theorem Prover, the first prover to support induction in a
 general setting.</p>

 <p>For a detailed description of how ACL2 generates induction schemes see <a
 href='http://www.cs.utexas.edu/users/moore/publications/acl2-induction-heuristics.pdf'>``ACL2
 Induction Heuristics.''</a> That paper is intended for a general audience
 familiar with induction but not necessarily familiar with theorem provers or
 ACL2.  However, it can also serve as a guided tour through that part of the
 ACL2 source code that creates and selects induction schemes.</p>")

(defxdoc infected-constraints
  :parents (encapsulate)
  :short "@(tsee Events) affecting @(see constraint)s of @(tsee encapsulate)s"
  :long "<p>Here we explain briefly the two kinds of @('"Infected"') @(see
 warnings) that are sometimes printed near the end of the output from @(tsee
 encapsulate) @(see events).  Also see @(see constraint) for a more complete
 discussion of constraints produced by @('encapsulate') events, and see @(see
 subversive-recursions) for a more complete discussion of the second kind of
 @('"Infected"') warning mentioned below, in the last example.</p>

 <p>An @('"Infected"') warning indicates that an event introducing a function
 symbol inside @('encapsulate') event affects the constraint exported for the
 function introduced in the @(see signature) list of that @('encapsulate').
 That function is typically introduced with @(tsee defun), but it could be
 introduced in a signature list of a subsidiary @('encapsulate') event or in a
 @(tsee defchoose) event.  Below we'll discuss the case of @('defun'), but the
 others are completely analogous for an @('"Infected"') warning.</p>

 <p>Let's compare the following three examples.</p>

 <p><b>EXAMPLE 1</b>.</p>

 @({
  (encapsulate
   (((sig-fn *) => *))

   (local (defun sig-fn (x) (cons x x)))

   (defun foo (x)
     (sig-fn x))

   (defthm foo-prop
     (consp (foo x))))
 })

 <p>In Example 1 above, ACL2 warns us that the @('defun') event is having an
 effect on the constraint of another function (more on that below).</p>

 @({
 ACL2 Warning [Infected] in ( ENCAPSULATE (((SIG-FN * ...) ...) ...)
 ...):  Note that the definitional equation for FOO infects the constraint
 of this encapsulation....
 })

 <p>Indeed, just above that warning we see that the definitional equation for
 @('foo') is part of the constraint not only on @('foo') but also on
 @('sig-fn').</p>

 @({
 The following constraint is associated with both of the functions FOO
 and SIG-FN:

 (AND (EQUAL (FOO X) (SIG-FN X)) (CONSP (FOO X)))
 })

 <p>The warning message suggests the desirability of moving the definition out
 of the @('encapsulate'), if possible.  That is not possible above: the
 definition of @('foo') cannot be moved before the @('encapsulate') because it
 depends syntactically on @('sig-fn'), and it cannot be moved after the
 @('encapsulate') because it depends syntactically on @('foo-prop').</p>

 <p>By contrast, in the next two examples the @('defun') of @('foo') can be
 moved before, respectively after, the @('encapsulate').  In these simple
 cases, ACL2 in effect does that for us automatically, and the constraint for
 @('sig-fn') doesn't mention @('foo') or vice-versa.  In other cases, you might
 want to think about how to move the relevant @('defun') (for @('foo'), in this
 case) manually.</p>

 <p><b>EXAMPLE 2</b> (moving the definition of @('foo') before the
 @('encapsulate')).</p>

 @({
  (encapsulate
   (((sig-fn *) => *))

   (local (defun sig-fn (x) (cons x x)))

   (defun foo (x)
     x)

   (defthm foo-prop
     (equal (foo x) (car (sig-fn x)))))
 })

 <p><b>EXAMPLE 3</b> (moving the definition of @('foo') after the
 @('encapsulate')).</p>

 @({
  (encapsulate
   (((sig-fn *) => *))

   (local (defun sig-fn (x) (cons x x)))

   (defun foo (x)
     (sig-fn x))

   (defthm foo-prop
     (consp (sig-fn x)))
   )
 })

 <p>We now turn to a second kind of @('"Infected"') warning for a @('defun')
 form inside an @('encapsulate') form.  This type of warning indicates that in
 addition to the effect on constraints discussed above, ACL2 refuses to store
 an induction scheme or a built-in @(see type-prescription) rule for the
 @('defun').  Consider the following example.</p>

 <p><b>EXAMPLE 4</b>.</p>

 @({
  (encapsulate
    (((f *) => *))

    (local (defun f (x) (cdr x)))

    (defthm f-prop
      (equal (f nil) nil))

    (defun g (x)
      (if (consp x)
          (g (f x))
        x)))
 })

 <p>As in Example 1 above, the exported constraint is on both function symbols
 that have been introduced, reported as follows by ACL2.</p>

 @({
 The following constraint is associated with both of the functions G
 and F:

 (AND (EQUAL (F NIL) NIL)
      (EQUAL (G X) (IF (CONSP X) (G (F X)) X)))
 })

 <p>But this time, in addition, no induction scheme is stored for @('g'), nor
 is any built-in @(see type-prescription) rule stored for @('g'), as indicated
 by a warning that begins as follows.</p>

 @({
 ACL2 Warning [Infected] in ( ENCAPSULATE (((F * ...) ...) ...) ...):
 Note that G is ``subversive.''  See :DOC infected-constraints....
 })

 <p>Note that if @('f') and @('g') had been similarly defined at the top level
 instead of within an @('encapsulate'), a type-prescription rule would be added
 asserting that ``the type of G is described by the theorem @('(NOT (CONSP (G
 X)))').''  But there is no such rule introduced in this ``subversive'' case.
 Indeed, this ``theorem'' is not actually a theorem after evaluating the
 @('encapsulate'), as it does not even follow from the stronger
 axiom (stronger, that is, than the constraint displayed above) that both
 @('f') and @('g') are the identity function.</p>

 <p>See @(see subversive-recursions) for more details, including criteria for
 when this ``subversive'' situation arises and what might be done to address
 it.  Also see @(see constraint) for a general discussion of constraints
 introduced by an @(tsee encapsulate) event.</p>")

(defxdoc initialize-event-user
  :parents (output-controls)
  :short "User-supplied code to initiate @(see events)"
  :long "<p>This utility is intended for system hackers, not standard ACL2
 users.</p>

 <p>See @(see finalize-event-user) to see how to supply code to be run at the
 end of @(see events).  We assume familiarity with @('finalize-event-user');
 here we focus on how to supply code for the beginning as well as the end of
 events.</p>

 <p>As with @(see finalize-event-user), you attach your own function of
 argument list @('(ctx qbody state)') to @('initialize-event-user').  (See
 @(see finalize-event-user) for discussion of @('ctx') and @('body').)  The
 attachment should return @('state') and have a trivial guard, requiring
 (implicitly) only that @('state') satisfies @('state-p') unless you use trust
 tags to avoid that requirement.  For example:</p>

 @({
  (defattach-system initialize-event-user initialize-event-user-test)
 })

 <p>Why would you want to do this?  Presumably you are building a system on top
 of ACL2 and you want to track your own data.  For example, suppose you want to
 save the time in some @(see state) global variable, @('my-time').  You could
 do the following.</p>

 @({
  (defun my-init (ctx body state)
    (declare (xargs :stobjs state
                    :guard-hints
                    (("Goal" :in-theory (enable read-run-time))))
             (ignore ctx body))
    (mv-let (seconds state)
            (read-run-time state)
            (f-put-global 'start-time seconds state)))

  (defun my-final (ctx body state)
    (declare (xargs :stobjs state
                    :guard-hints
                    (("Goal" :in-theory (enable read-run-time))))
             (ignore ctx body))
    (mv-let (seconds state)
            (read-run-time state)
            (prog2$ (if (boundp-global 'start-time state)
                        (cw "Time: ~x0 seconds~%"
                            (- seconds (fix (@ start-time))))
                      (cw "BIG SURPRISE!~%"))
                    (f-put-global 'end-time seconds state))))

  (defattach-system initialize-event-user my-init)
  (defattach-system finalize-event-user my-final)
 })

 <p>Here is an abbreviated log, showing the time being printed at the end.</p>

 @({
  ACL2 !>(thm (equal (append (append x y) x y x y x y x y)
                     (append x y x y x y x y x y)))

  *1 (the initial Goal, a key checkpoint) is pushed for proof by induction.
  ....
  ACL2 Error in ( THM ...):  See :DOC failure.

  ******** FAILED ********
  Time: 869/100 seconds
  ACL2 !>
 })")

(defxdoc installation
  :parents (acl2 about-acl2)
  :short "Installing ACL2"
  :long "<p>See the @(see installation-instructions) for steps to install ACL2
 on Unix-like systems (Linux, macOS, and FreeBSD).</p>

 <p>If you encounter problems installing ACL2, or need more information, see @(see
 installation-support).</p>

 <p>See @(see copyright) for information about copyright, license, and
 authorship of the ACL2 system, and see @(see acknowledgments) for
 sponsorship information.</p>

 <p>For a variant of ACL2 that supports reasoning about the real numbers, see
 @(see real).</p>

 <p>See @(see mailing-lists) for information about mailing lists for ACL2
 users, including how to post and how to access archives.</p>

 <p>ACL2 may be exported to any countries except those subject to embargoes
 under various laws administered by the Office of Foreign Assets
 Control (&ldquo;OFAC&rdquo;) of the U. S. Department of the Treasury.</p>

 <p>For more information about getting started with ACL2, see @(see
 start-here).  Also see @(see using-acl2) for information about running ACL2
 and about its @(see documentation).</p>")

(order-subtopics installation
  (installation-instructions obtaining-common-lisp
    installation-support
    using-acl2))

(defxdoc installation-instructions
  :parents (installation)
  :short "ACL2 installation instructions for Unix-like systems"
  :long "<p>These instructions describe how to install ACL2 on &ldquo;Unix-like
 systems&rdquo;, including Linux, macOS (with Intel or ARM processors),
 and FreeBSD.  To install ACL2 on Windows, see @(see windows-installation).</p>

 <p>ACL2 installations include both the ACL2 system and the open-source ACL2
 libraries developed by the ACL2 community, called the
 <see topic='@(url community-books)'>Community Books</see>.</p>

 <ol>

 <li>Decide which of the following you want to install:
   <ul>
         <li>The <b>latest ACL2 release</b>
         (<see topic='@(url note-8-6)'>version 8.6</see>).  The release is
         stable and very well tested but does not include any improvements
         or fixes made since October, 2024.  It may be appropriate
         if you do not need the very latest tools and libraries and
         do not plan to contribute to the @(see community-books).  A
         <see topic='@(url pre-built-binary-distributions)'>pre-built
         binary distribution</see> of the release may be available for
         your platform, which can let you avoid following these installation
         instructions.</li>

         <li>The <b>latest development snapshot</b> from GitHub (likely at most
         a few days old). Development snapshots are only minimally tested and
         may (rarely) have problems.  However, they provide the latest iteration
         of ACL2 and the @(see community-books).  Use a development
         snapshot if you plan to
         <see topic='@(url github-commit-code-using-pull-requests)'>
         contribute</see> additions or changes to the
         @(see community-books), or if you plan to
         update your copy of ACL2 later.  Pre-built binary distributions of
         development snapshots are generally not available.</li>
   </ul>
 </li>

<p/>

 <li>Obtain a Common Lisp implementation if you don't already have one; see
 @(see obtaining-common-lisp).  (Note: Some of the
 @(see community-books) depend on @(see Quicklisp), and those are only
 guaranteed to work with CCL or SBCL.)</li><p/>

 <li>Depending on your decision in Step 1, download ACL2 by doing
     either of the following:
    <ul>
        <li><b>For the latest ACL2 release</b> (version 8.6):
          <ol>
            <li>Change to a directory that does not already contain a
            subdirectory called @('acl2-8.6').</li>
            <li>Download <a href='https://github.com/acl2-devel/acl2-devel/releases/download/8.6/acl2-8.6.tar.gz'>
            @('acl2-8.6.tar.gz')</a> to that directory.</li>
            <li>Execute the following:
            @({
            tar xfz acl2-8.6.tar.gz
            cd acl2-8.6
            })</li>
          </ol>
          The new subdirectory @('acl2-8.6') should now
          be your shell's current directory.
        </li>

        <li><b>Or, for the latest development snapshot</b>:
          <ol>
            <li>Change to a directory that does not already contain a
            subdirectory named @('acl2').</li>
            <li>Execute the following:
            @({
            git clone https://github.com/acl2/acl2
            cd acl2
            })</li>
          </ol>
          The new subdirectory @('acl2') should now be
          your shell's current directory.
        </li>
    </ul>
 </li><p/>

 <li>Compile ACL2:

 @({
 make LISP=<your_command_to_run_lisp>
 })

 where @('<your_command_to_run_lisp>') is a command that runs
 your selected Common LISP and is not merely a shell alias. The
 default for @('<your_command_to_run_lisp>') is @('ccl').

 <b>Note:</b> You will need GNU Make (preferably newer than Version 3.82).

 This will create an executable script named @('saved_acl2') (in the
 current directory) that can be used to run ACL2.</li><p/>

 <li>Optionally, test ACL2 as follows:
 @({
 ./saved_acl2
 :mini-proveall
 (quit)
 })
 You should see "Mini-proveall completed successfully." a few lines above
 the bottom of the output.</li><p/>

 <li>Certify some books, for example with

 @({
 make basic
 })

 or something fancier such as the following.

 @({
 (time nice make -j 8 ACL2=/u/smith/bin/acl2 basic) >& make-basic.log
 })

 This may take only a few minutes, depending your @('-j') value,
 your machine, and your host Common Lisp.  The
 resulting log should contain no occurrences of the string
 &ldquo;CERTIFICATION FAILED&rdquo;; a normal exit (status 0) should guarantee
 this.  If you want further options or additional explanation (e.g.,
 you can certify many more books with @('make regression'), and there is a
 discussion of avoiding root login), see @(see books-certification).</li>

 </ol>

 <p>You now have an executable script called @('saved_acl2') and
 access to certified community books.  Enjoy!  And please
 consider contributing to the ACL2 libraries; see @(see
 how-to-contribute).</p>")

(defxdoc installation-support
  :parents (installation)
  :short "Additional support for ACL2 installation"
  :long "<p>To install ACL2, it will generally suffice to see the
 @(see installation-instructions).  You should read the subtopics below only if
 those instructions were somehow not sufficient.  They provide alternate and
 additional information for obtaining and installing ACL2 and associated
 libraries.</p>")

(defxdoc instructions
  :parents (proof-builder)
  :short "Instructions to the interactive proof-builder"
  :long "<p>See @(see proof-builder) for an introduction to the interactive
 ``proof-builder'' goal manager, which supports much more direct control of the
 proof process than is available by direct calls to the prover (as are normally
 made using @(tsee defthm) or @(tsee thm)).  In brief, typical use is to
 evaluate the form @('(verify SOME-GOAL)'), where @('SOME-GOAL') is a
 formula (i.e., term) that you would like to prove.  Various
 commands (instructions) are available at the resulting prompt; see @(see
 proof-builder-commands).  When the proof is completed, suitable invocation of
 the @('exit') command will print out a form containing an @(':instructions')
 field that provides the instructions that you gave interactively, so that this
 form can be evaluated non-interactively.</p>

 <p>Thus, also see @(see defthm) for the role of @(':instructions') in place of
 @(':')@(tsee hints).  As illustrated by the following example, the value
 associated with @(':instructions') is a list of interactive @(see
 proof-builder) commands.</p>

 @({
  Example:
  (defthm associativity-of-append
          (equal (append (append x y) z)
                 (append x (append y z)))
          :instructions
          (:induct (:dv 1) (:dv 1) :x :up :x (:dv 2) := (:drop 2)
           :top (:dv 2) :x :top :s :bash))
 })

 <p>See @(see proof-builder-commands) for a list of supported interactive
 proof-builder instructions and links to their documentation.</p>

 <p>Below, we describe a capability for supplying @(':instructions') as
 @(':')@(tsee hints).</p>

 <p>The most basic utilities for directing the discharge of a proof obligation
 are @(':')@(tsee hints) and (less commonly) @(':instructions').  Individual
 instructions may call the prover with @(':hints'); in that sense, prover hints
 may occur inside instructions.  We now describe how, on the other hand,
 instructions may occur inside hints.</p>

 <p>ACL2 supports @(':instructions') as a hints keyword.  The following example
 forms the basis for our running example.  This example does not actually need
 hints, but imagine that the inductive step &mdash; which is "Subgoal *1/2"
 &mdash; was difficult.  You could submit that goal to @(tsee verify), do an
 interactive proof, submit @('(exit t)') to obtain the list of
 @(':instructions'), and then paste in those instructions.  When you submit the
 resulting event, you might see the following.  Below we'll explain the hint
 processing.</p>

 @({
  ACL2 !>(thm (equal (append (append x y) z)
                     (append x (append y z)))
              :hints (("Subgoal *1/2"
                       :instructions
                       (:promote (:dv 1) (:dv 1) :x :up :x (:dv 2) :=
                        (:drop 2) :top (:dv 2) :x :top :s))))

  Name the formula above *1.

  Perhaps we can prove *1 by induction.  Three induction schemes are
  suggested by this conjecture.  Subsumption reduces that number to two.
  However, one of these is flawed and so we are left with one viable
  candidate.

  We will induct according to a scheme suggested by (BINARY-APPEND X Y).
  This suggestion was produced using the :induction rule BINARY-APPEND.
  If we let (:P X Y Z) denote *1 above then the induction scheme we'll
  use is
  (AND (IMPLIES (AND (NOT (ENDP X)) (:P (CDR X) Y Z))
                (:P X Y Z))
       (IMPLIES (ENDP X) (:P X Y Z))).
  This induction is justified by the same argument used to admit BINARY-APPEND.
  When applied to the goal at hand the above induction scheme produces
  two nontautological subgoals.

  [Note:  A hint was supplied for the goal below.  Thanks!]

  Subgoal *1/2
  (IMPLIES (AND (NOT (ENDP X))
                (EQUAL (APPEND (APPEND (CDR X) Y) Z)
                       (APPEND (CDR X) Y Z)))
           (EQUAL (APPEND (APPEND X Y) Z)
                  (APPEND X Y Z))).

  But the trusted :CLAUSE-PROCESSOR function PROOF-BUILDER-CL-PROC replaces
  this goal by T.

  Subgoal *1/1
  (IMPLIES (ENDP X)
           (EQUAL (APPEND (APPEND X Y) Z)
                  (APPEND X Y Z))).

  By the simple :definition ENDP we reduce the conjecture to

  Subgoal *1/1'
  (IMPLIES (NOT (CONSP X))
           (EQUAL (APPEND (APPEND X Y) Z)
                  (APPEND X Y Z))).

  But simplification reduces this to T, using the :definition BINARY-APPEND
  and primitive type reasoning.

  That completes the proof of *1.

  Q.E.D.

  Summary
  Form:  ( THM ...)
  Rules: ((:DEFINITION BINARY-APPEND)
          (:DEFINITION ENDP)
          (:DEFINITION NOT)
          (:FAKE-RUNE-FOR-TYPE-SET NIL)
          (:INDUCTION BINARY-APPEND))
  Time:  0.02 seconds (prove: 0.01, print: 0.01, other: 0.00)

  Proof succeeded.
  ACL2 !>
 })

 <p>To understand how the @(':instructions') supplied above were processed,
 view the interactive proof-builder instruction interpreter as a
 ``clause-processor'': a function that takes an input goal and returns a list
 of goals (which can be the empty list).  Such a function has the property that
 if all goals in that returned list are theorems, then so is the input goal.
 This view of the interactive proof-builder instruction interpreter as a
 clause-processor leads to the following crucial observation.</p>

 <p><b>IMPORTANT!</b>.  Each call of the interactive proof-builder instruction
 interpreter is treated as a standalone clause-processor that is insensitive to
 the surrounding prover environment.  In particular:</p>

 <ul>

 <li>The interactive proof-builder's theory is not sensitive to @(':in-theory')
 @(see hints) already processed in the surrounding proof.  Indeed, the current
 theory for which proof-builder commands are processed is just the current
 theory of the ACL2 logical @(see world), i.e., the value of
 @('(current-theory :here)').  Moreover, references to
 @('(current-theory :here)') in a proof-builder @('in-theory') command, even
 implicit references such as provided by @(tsee enable) and @(tsee disable)
 expressions, are also references to the current theory of the ACL2 logical
 @(see world).</li>

 <li>The @(see rune)s used during an @(':instructions') hint are not tracked
 beyond that hint, hence may not show up in the @(see summary) of the overall
 proof.  Again, think of the @(':instructions') hint as a @(see
 clause-processor) call, which has some effect not tracked by the surrounding
 proof other than for the child goals that it returns.</li>

 </ul>

 <p>We continue now with our discussion of the interactive proof-builder
 instruction interpreter as a clause-processor.</p>

 <p>In the example above, the input goal (@('"Subgoal *1/2"')) was processed
 by the proof-builder instruction interpreter.  The result was the empty goal
 stack, therefore proving the goal, as reported in the output, which we repeat
 here.</p>

 @({
  [Note:  A hint was supplied for the goal below.  Thanks!]

  Subgoal *1/2
  (IMPLIES (AND (NOT (ENDP X))
                (EQUAL (APPEND (APPEND (CDR X) Y) Z)
                       (APPEND (CDR X) Y Z)))
           (EQUAL (APPEND (APPEND X Y) Z)
                  (APPEND X Y Z))).

  But the trusted :CLAUSE-PROCESSOR function PROOF-BUILDER-CL-PROC replaces
  this goal by T.
 })

 <p><b>Remark.</b> This brief remark can probably be ignored, but we include it
 for completeness.  The @(':CLAUSE-PROCESSOR') message above may be surprising,
 since the hint attached to @('"Subgoal *1/2"') is an @(':instructions')
 hint, not a @(':clause-processor') hint.  But @(':instructions') is actually a
 custom keyword hint (see @(see custom-keyword-hints)), and may be thought of
 as a macro that expands to a @(':')@(tsee clause-processor) hint, one that
 specifies @('proof-builder-cl-proc') as the clause-processor function.  The
 keen observer may notice that the clause-processor is referred to as
 ``trusted'' in the above output.  Normally one needs a trust tag (see @(see
 defttag)) to install a trusted clause-processor, but that is not the case for
 the built-in clause-processor, @('proof-builder-cl-proc').  Finally, we note
 that @(':instructions') @(see hints) are ``spliced'' into the hints as
 follows: the appropriate @(':')@(tsee clause-processor) hint replaces the
 @(':instructions') hint, and the other hints remain intact.  It may seems
 surprising that one can thus, for example, use @(':instructions') and
 @(':in-theory') together; but although the @(':in-theory') hint will have no
 effect on execution of the @(':instructions') (see first bullet above), the
 @(':in-theory') hint will apply in the usual manner to any child goals (see
 @(see hints-and-the-waterfall)).  End of Remark.</p>

 <p>Now consider the case that the supplied instructions do not prove the goal.
 That is, suppose that the execution of those instructions results in a
 non-empty goal stack.  In that case, the resulting goals become children of
 the input goals.  The following edited log provides an illustration using a
 modification of the above example, this time with a single instruction that
 splits into two cases.</p>

 @({
  ACL2 !>(thm (equal (append (append x y) z)
                     (append x (append y z)))
              :hints (("Subgoal *1/2"
                       :instructions
                       ((:casesplit (equal x y))))))

  [[ ... output omitted ... ]]

  Subgoal *1/2
  (IMPLIES (AND (NOT (ENDP X))
                (EQUAL (APPEND (APPEND (CDR X) Y) Z)
                       (APPEND (CDR X) Y Z)))
           (EQUAL (APPEND (APPEND X Y) Z)
                  (APPEND X Y Z))).

  We now apply the trusted :CLAUSE-PROCESSOR function PROOF-BUILDER-CL-PROC
  to produce two new subgoals.

  Subgoal *1/2.2

  [[ ... output omitted ... ]]

  Subgoal *1/2.1

  [[ ... output omitted ... ]]
 })

 <p>We have seen that an @(':instructions') hint may produce zero or more
 subgoals.  There may be times where you wish to insist that it produce zero
 subgoals, i.e., that it prove the desired goal.  The interactive
 proof-builder's `@('finish')' command works nicely for this purpose.  For
 example, the following form is successfully admitted, but if you delete some
 of the commands (for example, the @(':s') command at the end), you will see an
 informative error message.</p>

 @({
  (thm (equal (append (append x y) z)
              (append x (append y z)))
       :hints (("Subgoal *1/2"
                :instructions
                ((finish :promote (:dv 1) (:dv 1) :x :up :x (:dv 2) :=
                         (:drop 2) :top (:dv 2) :x :top :s)))))
 })

 <p>If an :instructions hint of the form @('((finish ...))') fails to prove the
 goal, the clause-processor is deemed to have caused an error.  Indeed, any
 ``failure'' of a supplied proof-builder instruction will be deemed to cause an
 error.  In this case, you should see an error message such as the
 following:</p>

 @({
  Saving proof-builder error state; see :DOC instructions.  To retrieve:

  (RETRIEVE :ERROR1)
 })

 <p>In this case, you can evaluate the indicated @(tsee retrieve) command in
 the ACL2 read-eval-print loop, to get to the point of failure.</p>

 <p>You may have noticed that there is no output from the interactive
 proof-builder in the examples above.  This default behavior prevents confusion
 that could arise from use of proof-builder commands that call the theorem
 prover such as @('prove'), @('bash'), @('split'), and @('induct').  These
 commands produce output for what amounts to a fresh proof attempt, which could
 confuse attempts to understand the surrounding proof log.  You can override
 the default behavior by providing a command of the form</p>

 <code> @('(comment inhibit-output-lst VAL)') </code>

 <p>where @('VAL') is either the keyword @(':SAME') (indicating that no change
 should be made to which output is inhibited) or else is a legal value for
 inhibited output; see @(see set-inhibit-output-lst).  The following two
 variants of the immediately preceding @('THM') form will each produce output
 from the interactive proof-builder commands, assuming in the first variant
 that output hasn't already been inhibited.</p>

 @({
  (thm (equal (append (append x y) z)
                     (append x (append y z)))
              :hints (("Subgoal *1/2"
                       :instructions
                       ((comment inhibit-output-lst :same)
                        (:casesplit (equal x y))))))

  (thm (equal (append (append x y) z)
                     (append x (append y z)))
              :hints (("Subgoal *1/2"
                       :instructions
                       ((comment inhibit-output-lst (proof-tree))
                        (:casesplit (equal x y))))))
 })

 <p>Note that such a @('comment') instruction must be provided explicitly
 (i.e., not by way of a proof-builder @(see macro-command)) as the first
 instruction, in order to have the effect on inhibited output that is described
 above.</p>

 <p>The following contrived example gives a sense of how one might want to use
 @(':instructions') within @(':')@(tsee hints).  If you submit the following
 theorem</p>

 @({
  (thm (implies (true-listp x)
                (equal (reverse (reverse x)) x)))
 })

 <p>then you will see the following checkpoint printed with the @(see
 summary).</p>

 @({
  Subgoal *1/3''
  (IMPLIES (AND (CONSP X)
                (EQUAL (REVAPPEND (REVAPPEND (CDR X) NIL) NIL)
                       (CDR X))
                (TRUE-LISTP (CDR X)))
           (EQUAL (REVAPPEND (REVAPPEND (CDR X) (LIST (CAR X)))
                             NIL)
                  X))
 })

 <p>This suggests proving the following theorem.  Here we state it using @(tsee
 defthmd), so that it is immediately disabled.  Normally disabling would be
 unnecessary, but for our contrived example it is useful to imagine disabling
 it, say because we are following a methodology that tends to keep @(see
 rewrite) rules disabled.</p>

 @({
  (defthmd revappend-revappend
    (equal (revappend (revappend x y) z)
           (revappend y (append x z))))
 })

 <p>We might then enter the interactive @(see proof-builder) to prove the
 original theorem interactively, as follows.</p>

 @({
  ACL2 !>(verify (implies (true-listp x)
                          (equal (reverse (reverse x)) x)))
  ->: bash
  ***** Now entering the theorem prover *****
  Goal'

  ([ A key checkpoint:

  Goal'
  (IMPLIES (TRUE-LISTP X)
           (EQUAL (REVAPPEND (REVAPPEND X NIL) NIL)
                  X))

  Goal' is subsumed by a goal yet to be proved.

  ])

  Q.E.D.

  Creating one new goal:  (MAIN . 1).

  The proof of the current goal, MAIN, has been completed.  However,
  the following subgoals remain to be proved:
    (MAIN . 1).
  Now proving (MAIN . 1).
  ->: th ; show current goal ("th" for "theorem")
  *** Top-level hypotheses:
  1. (TRUE-LISTP X)

  The current subterm is:
  (EQUAL (REVAPPEND (REVAPPEND X NIL) NIL)
         X)
  ->: p ; show current subterm only
  (EQUAL (REVAPPEND (REVAPPEND X NIL) NIL)
         X)
  ->: 1 ; dive to first argument
  ->: p
  (REVAPPEND (REVAPPEND X NIL) NIL)
  ->: sr ; show-rewrites

  1. REVAPPEND-REVAPPEND (disabled)
    New term: (REVAPPEND NIL (APPEND X NIL))
    Hypotheses: <none>
    Equiv: EQUAL

  2. REVAPPEND
    New term: (AND (CONSP (REVAPPEND X NIL))
                   (REVAPPEND (CDR (REVAPPEND X NIL))
                              (LIST (CAR (REVAPPEND X NIL)))))
    Hypotheses: <none>
    Equiv: EQUAL
  ->: (r 1) ; rewrite with rule #1 above
  Rewriting with REVAPPEND-REVAPPEND.
  ->: p
  (REVAPPEND NIL (APPEND X NIL))
  ->: top ; move to the top of the conclusion, making it the current subterm
  ->: p
  (EQUAL (REVAPPEND NIL (APPEND X NIL)) X)
  ->: prove ; finish the proof
  ***** Now entering the theorem prover *****

  Q.E.D.

  *!*!*!*!*!*!* All goals have been proved! *!*!*!*!*!*!*
  You may wish to exit.
  ->: (exit t) ; the argument, t, causes :instructions to be printed
  (DEFTHM T
          (IMPLIES (TRUE-LISTP X)
                   (EQUAL (REVERSE (REVERSE X)) X))
          :INSTRUCTIONS (:BASH (:DV 1)
                               (:REWRITE REVAPPEND-REVAPPEND)
                               :TOP :PROVE))
   NIL
  ACL2 !>(thm
          (IMPLIES (TRUE-LISTP X)
                   (EQUAL (REVERSE (REVERSE X)) X))
          :hints (("Goal"
                   :INSTRUCTIONS ; copy what was printed above:
                   (:BASH (:DV 1)
                          (:REWRITE REVAPPEND-REVAPPEND)
                          :TOP :PROVE))))
  Goal'

  Q.E.D.

  Q.E.D.

  Q.E.D.

  Summary
  Form:  ( THM ...)
  Rules: NIL
  Hint-events: ((:CLAUSE-PROCESSOR PROOF-BUILDER-CL-PROC))
  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)

  Proof succeeded.
  ACL2 !>
 })

 <p>Finally we present an even more contrived example, based on the one above.
 This example illustrates that there is actually no limit imposed on the
 nesting of @(':instructions') within @(':')@(tsee hints) within
 @(':instructions'), and so on.  Notice the indication of nesting levels:
 ``@('1>')'' to ``@('<1')'' for output from nesting level 1, and ``@('2>')'' to
 ``@('<2')'' for output from nesting level 2.</p>

 @({
  (thm (implies (true-listp x)
                (equal (reverse (reverse x)) x))
       :hints (("Goal"
                :instructions
                ((comment inhibit-output-lst :same)
                 (:prove
                  :hints (("Goal" :in-theory (disable append))
                          ("Subgoal *1/3''"
                           :instructions
                           ((comment inhibit-output-lst :same)
                            :bash
                            (:dv 1)
                            (:rewrite revappend-revappend)))))))))
 })

 <p>Here is an edited version of the resulting log.</p>

 @({
  [Note:  A hint was supplied for the goal above.  Thanks!]

  [[1> Executing proof-builder instructions]]

  ->: (COMMENT INHIBIT-OUTPUT-LST :SAME)
  ->: (:PROVE
           :HINTS
           (("Goal" :IN-THEORY (DISABLE APPEND))
            ("Subgoal *1/3''" :INSTRUCTIONS ((COMMENT INHIBIT-OUTPUT-LST :SAME)
                                             :BASH (:DV 1)
                                             (:REWRITE REVAPPEND-REVAPPEND)))))
  ***** Now entering the theorem prover *****

  [[ ... output omitted ... ]]

  [Note:  A hint was supplied for the goal below.  Thanks!]

  Subgoal *1/3''
  (IMPLIES (AND (CONSP X)
                (EQUAL (REVAPPEND (REVAPPEND (CDR X) NIL) NIL)
                       (CDR X))
                (TRUE-LISTP (CDR X)))
           (EQUAL (REVAPPEND (REVAPPEND (CDR X) (LIST (CAR X)))
                             NIL)
                  X)).

  [[2> Executing proof-builder instructions]]

  ->: (COMMENT INHIBIT-OUTPUT-LST :SAME)
  ->: :BASH
  ***** Now entering the theorem prover *****

  [Note:  A hint was supplied for the goal above.  Thanks!]

  But we have been asked to pretend that this goal is subsumed by the
  yet-to-be-proved |PROOF-BUILDER Goal|.

  Q.E.D.

  Creating one new goal:  (MAIN . 1).

  The proof of the current goal, MAIN, has been completed.  However,
  the following subgoals remain to be proved:
    (MAIN . 1).
  Now proving (MAIN . 1).
  ->: (:DV 1)
  ->: (:REWRITE REVAPPEND-REVAPPEND)
  Rewriting with REVAPPEND-REVAPPEND.

  [[<2 Completed proof-builder instructions]]

  We now apply the trusted :CLAUSE-PROCESSOR function PROOF-BUILDER-CL-PROC
  to produce one new subgoal.

  Subgoal *1/3'''

  [[ ... output omitted ... ]]

  [[<1 Completed proof-builder instructions]]
 })

 <p>The nesting levels are independent of whether or not output is enabled; for
 example, if the first @('(comment ...)') form below is omitted, then we will
 see only the output bracketed by ``@('2>')'' to ``@('<2')''.  Note also that
 these levels are part of the error states saved for access by @(tsee retrieve)
 (as indicated above); for example, a failure at level 1 would be associated
 with symbol @(':ERROR1') as indicated above, while a failure at level 2 would
 be associated with symbol @(':ERROR2').</p>")

(defxdoc int=
  :parents (numbers acl2-built-ins)
  :short "Test equality of two integers"
  :long "<p>@('(int= x y)') is logically equivalent to @('(equal x y)').</p>

 <p>Unlike @(tsee equal), @('int=') requires its arguments to be integers (or
 else causes a @(see guard) violation; see @(see guard)).  @('Int=') is
 intended to execute more efficiently on integers than @(tsee equal) or @(tsee
 =), though this may not be true for all host Lisps.</p>

 @(def int=)")

(defxdoc integer-length
  :parents (numbers acl2-built-ins)
  :short "Number of bits in two's complement integer representation"
  :long "<p>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.</p>

 <p>The @(see 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.</p>

 @(def integer-length)")

(defxdoc integer-listp
  :parents (numbers lists acl2-built-ins)
  :short "Recognizer for a true list of integers"
  :long "<p>The predicate @('integer-listp') tests whether its argument is a
 true list of integers.</p>

 @(def integer-listp)")

(defxdoc integer-range-p
  :parents (numbers acl2-built-ins)
  :short "Recognizer for integers between two bounds."
  :long "<p>The predicate @('(integer-range-p lower upper x)') tests whether
  @('x') is an integer greater than or equal to @('lower') and less than
  @('upper').</p>

  @(def integer-range-p)")

(defxdoc integerp
  :parents (numbers acl2-built-ins)
  :short "Recognizer for whole numbers"
  :long "<p>@('(integerp x)') is true if and only if @('x') is an integer.</p>")

(defxdoc interesting-applications
  :parents (acl2-tutorial)
  :short "Some industrial examples of ACL2 use"
  :long "<p>ACL2 is an interactive system in which you can model digital
 artifacts and guide the system to mathematical proofs about the behavior of
 those models.  It has been used at such places as AMD, Centaur, IBM, and
 Rockwell Collins to verify interesting properties of commercial designs.  It
 has been used to verify properties of models of microprocessors, microcode,
 the Sun Java Virtual Machine, operating system kernels, other verifiers, and
 interesting algorithms.</p>

 <p>Here we list just a few of the industrially-relevant results obtained with
 ACL2.  Reading the list may help you decide you want to learn how to use ACL2.
 If you do decide you want to learn more, we recommend that you take the @(see
 tours) after you leave this page.</p>

 <p>ACL2 was used at <b>Motorola Government Systems</b> to certify several
 microcode programs for the <b>Motorola CAP digital signal processor</b>,
 including a comparator sort program that is particularly subtle. In the same
 project, ACL2 was used to model the CAP at both the pipelined architectural
 level and the instruction set level.  The architectural model was bit- and
 cycle-accurate: it could be used to predict every bit of memory on every
 cycle.  The models were proved equivalent under certain hypotheses, the most
 important being a predicate that analyzed the microcode for certain pipeline
 hazards. This predicate defined what the hazards were, syntactically, and the
 equivalence of the two models established the correctness of this syntactic
 characterization of hazards.  Because ACL2 is a functional programming
 language, the ACL2 models and the hazard predicate could be executed.  ACL2
 executed a microcode interpreter several times faster than the hardware
 simulator could execute it &mdash; with assurance that the answers were
 equivalent.  In addition, the ACL2 hazard predicate was executed on over fifty
 microcode programs written by Motorola engineers and extracted from the ROM
 mechanically. Hazards were found in some of these.  (See, for example, Bishop
 Brock and Warren. A. Hunt, Jr. ``Formal analysis of the Motorola CAP DSP.'' In
 <i>Industrial-Strength Formal Methods</i>. Springer-Verlag, 1999.)</p>

 <p>ACL2 was used at <b>Advanced Micro Devices</b> (AMD) to verify the
 compliance of the <b>AMD Athlon</b>'s (TM) elementary floating point operations
 with their IEEE 754 specifications. This followed ground-breaking work in 1995
 when ACL2 was used to prove the correctness of the microcode for
 floating-point division on the <b>AMD K5</b>. The AMD Athlon work proved
 addition, subtraction, multiplication, division, and square root compliant
 with the IEEE standard. Bugs were found in RTL designs. These bugs had
 survived undetected in hundreds of millions of tests but were uncovered by
 ACL2 proof attempts. The RTL in the fabricated Athlon FPU has been
 mechanically verified by ACL2.  Similar ACL2 proofs have been carried out for
 every major AMD FPU design fabricated since the Athlon.  (See for example,
 David Russinoff. ``A mechanically checked proof of correctness of the AMD5K86
 floating-point square root microcode''.  <i>Formal Methods in System
 Design</i> Special Issue on Arithmetic Circuits, 1997.)</p>

 <p>ACL2 was used at <b>IBM</b> to verify the floating point divide and square
 root on the <b>IBM Power 4</b>.  (See Jun Sawada. ``Formal verification of
 divide and square root algorithms using series calculation''. In
 <i>Proceedings of the ACL2 Workshop 2002</i>, Grenoble, April 2002.)</p>

 <p>ACL2 was used to verify floating-point addition/subtraction instructions
 for the <b>media unit</b> from <b>Centaur Technology</b>'s 64-bit,
 X86-compatible microprocessor. This unit implements over one hundred
 instructions, with the most complex being floating-point
 addition/subtraction. The media unit can add/subtract four pairs of
 floating-point numbers every clock cycle with an industry-leading two-cycle
 latency. The media unit was modeled by translating its Verilog design into an
 HDL deeply embedded in the ACL2 logic. The proofs used a combination of AIG-
 and BDD-based symbolic simulation, case splitting, and theorem proving.  (See
 Warren A. Hunt, Jr. and Sol Swords. ``Centaur Technology Media Unit
 Verification''. In <i>CAV '09: Proceedings of the 21st International</i>
 <b>Conference on Computer Aided Verification</b>, pages 353&ndash;367, Berlin,
 Heidelberg, 2009. Springer-Verlag.)</p>

 <p><b>Rockwell Collins</b> used ACL2 to prove information flow properties
 about its <b>Advanced Architecture MicroProcessor 7 Government Version
 (AAMP7G)</b>, a Multiple Independent Levels of Security (MILS) device for use
 in cryptographic applications. The AAMP7G provides MILS capability via a
 verified secure hardware-based separation kernel. The AAMP7G's design was
 proved to achieve MILS using ACL2, in accordance with the standards set by
 EAL-7 of the Common Criteria and Rockwell Collins has received National
 Security Agency (NSA) certification for the device based on this work.  (See
 Matthew M. Wilding, David A. Greve, Raymond J. Richards, and David S. Hardin.
 ``Formal Verification of Partition Management for the AAMP7G
 Microprocessor''. In <i>Design and Verification of Microprocessor Systems for
 High-Assurance Applications</i>, David S. Hardin, ed., pages 175&ndash;191,
 Springer US, 2010.)</p>

 <p>Key properties of the <b>Sun Java Virtual Machine</b> and its <b>bytecode
 verifier</b> were verified in ACL2. Among the properties proved were that
 certain invariants are maintained by <b>class loading</b> and that the
 bytecode verifier ensures that execution is safe. In addition, various <b>JVM
 bytecode programs</b> have been verified using this model of the JVM.  (See
 Hanbing Liu. <i>Formal Specification and</i> <i>Verification of a JVM and its
 Bytecode Verifier</i>. PhD thesis, University of Texas at Austin, 2006.)</p>

 <p>The <b>Boyer-Moore fast string searching algorithm</b> was verified with
 ACL2, including a model of the JVM bytecode for the search algorithm itself
 (but not the preprocessing).  (See J S. Moore and Matt Martinez. ``A
 mechanically checked proof of the correctness of the Boyer-Moore fast string
 searching algorithm.'' In <i>Engineering Methods and Tools for Software Safety
 and Security</i> pages 267&ndash;284. IOS Press, 2009.)</p>

 <p>ACL2 was used to verify the fidelity between an <b>ACL2-like theorem
 prover</b> and a simple (``trusted by inspection'') <b>proof checker</b>,
 thereby establishing (up to the soundness of ACL2) the soundness of the
 ACL2-like theorem prover.  This project was only part of a much larger project
 in which the resulting ACL2 proof script was then hand-massaged into a script
 suitable for the ACL2-like theorem prover to process, generating a formal
 proof of its fidelity that has been checked by the trusted proof checker.
 (See Jared Davis.  <i>Milawa: A Self-Verifying Theorem Prover</i>.
 Ph.D. Thesis, University of Texas at Austin, December, 2009.)</p>

 <p>These are but a few of the interesting projects carried out with ACL2.
 Many of the authors mentioned above have versions of the papers on their web
 pages.  Also see @(see publications) and see the presentations in each of the
 ACL2 @(csee Workshops).</p>")

(defxdoc interfacing-tools
  :parents (top)
  :short "Libraries and tools for doing basic <see topic='@(url std/io)'>file
 i/o</see>, using raw <see topic='@(url quicklisp)'>Common Lisp
 libraries</see>, working with the <see topic='@(url oslib)'>operating
 system</see>, and interfacing with <see topic='@(url bridge)'>other
 programs</see>.")

(defxdoc intern
  :parents (symbolp packages acl2-built-ins)
  :short "Create a new symbol in a given package"
  :long "<p>@('(intern symbol-name symbol-package-name)') returns a symbol with
 the given @(tsee symbol-name) and the given @(tsee 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 @(see intern$).</p>

 <p>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 @(see intern-in-package-of-symbol).</p>

 <p>To see why @('intern') is so restricted consider @('(intern "X" "P")').
 In particular, is it a symbol and if so, what is its @(tsee
 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</p>

 @({
  (defpkg "P" '(COMMON-LISP::X))
 })

 <p>then in Common Lisp @('(symbol-package-name (intern "X" "P"))') returns
 @('"COMMON-LISP"').</p>

 <p>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 @(tsee 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.</p>")

(defxdoc intern$
  :parents (symbolp packages acl2-built-ins)
  :short "Create a new symbol in a given package"
  :long "<p>@('Intern$') is a macro that behaves the same as the macro @(tsee
 intern), except for weakening the restriction to a fixed set of package names
 so that any package name other than @('""') is legal.  See @(see 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.</p>

 <p>@('(Intern$ x y)') expands to:</p>

 @({
  (intern-in-package-of-symbol x (pkg-witness y))
 })

 <p>See @(see intern-in-package-of-symbol) and see @(see pkg-witness).</p>")

(defxdoc intern-in-package-of-symbol
  :parents (symbolp packages acl2-built-ins)
  :short "Create a symbol with a given name"
  :long "<p>Completion
  Axiom (@('completion-of-intern-in-package-of-symbol')):</p>

 @({
  (equal (intern-in-package-of-symbol x y)
         (if (and (stringp x)
                  (symbolp y))
             (intern-in-package-of-symbol x y)
           nil))
 })

 <p>@(see Guard) for @('(intern-in-package-of-symbol x y)'):</p>

 @({
  (and (stringp x) (symbolp y))
 })

 <p>Intuitively, @('(intern-in-package-of-symbol x y)') creates a symbol with
 @(tsee symbol-name) @('x') @(see intern)ed in the package containing @('y').
 More precisely, suppose @('x') is a string, @('y') is a symbol with @(tsee
 symbol-package-name) @('pkg') and that the @(tsee 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 @(tsee symbol-name) of @('ans') is @('x'), and the @(tsee
 symbol-package-name) of @('ans') is @('pkg'), unless @('x') is the @(tsee
 symbol-name) of some member of @('imports') with @(tsee symbol-package-name)
 @('ipkg'), in which case the @(tsee symbol-package-name) of @('ans') is
 @('ipkg').  Because @(tsee defpkg) requires that there be no duplications
 among the @(tsee symbol-name)s of the imports,
 @('intern-in-package-of-symbol') is uniquely defined.</p>

 <p>For example, suppose @('"MY-PKG"') was created by</p>

 @({
  (defpkg "MY-PKG" '(ACL2::ABC COMMON-LISP::CAR)).
 })

 <p>Let @('w') be @(''my-pkg::witness').  Observe that</p>

 @({
  (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"
 })

 <p>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.</p>

 <p>But another way to obtain a symbol in a given package is to create it with
 @('intern-in-package-of-symbol').</p>

 @({
  (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 COMMON-LISP::CAR (i.e., ACL2::CAR)

  (intern-in-package-of-symbol "car" w) is MY-PKG::|car|
 })")

(defxdoc intersection$
  :parents (lists acl2-built-ins)
  :short "Elements common to the given lists"
  :long "@({
  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
 })

 <p>@('(Intersection$ x y)') equals a list that contains the @('member')s of
 @('x') that are also @('member')s of @('y').  More precisely, the resulting
 list is the result of deleting from @('x') those members that are not members
 of @('y').  The optional keyword, @(':TEST'), has no effect logically, but
 provides the test (default @(tsee eql)) used for comparing members of the two
 lists.</p>

 <p>@('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)').</p>

 <p>The @(see guard) for a call of @('intersection$') (in the two cases just
 above) depends on the test.  In all cases, both arguments must satisfy @(tsee
 true-listp).  If the test is @(tsee eql), then one of the arguments must
 satisfy @(tsee eqlable-listp).  If the test is @(tsee eq), then one of the
 arguments must satisfy @(tsee symbol-listp).</p>

 <p>See @(see equality-variants) for a discussion of the relation between
 @('intersection$') and its variants:</p>

 <blockquote><p>@('(intersection-eq x lst)') is equivalent to @('(intersection$
 x lst :test 'eq)');</p>

 <p>@('(intersection-equal x lst)') is equivalent to @('(intersection$ x lst
 :test 'equal)').</p></blockquote>

 <p>In particular, reasoning about any of these primitives reduces to reasoning
 about the function @('intersection-equal').</p>

 <p>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.</p>

 <p>@('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').</p>

 @(def intersection-equal)")

(defxdoc intersection-theories
  :parents (theories theory-functions)
  :short "Intersect two @(see theories)"
  :long "@({
  Example:
  (intersection-theories (current-theory :here)
                         (theory 'arith-patch))

  General Form:
  (intersection-theories th1 th2)
 })

 <p>where @('th1') and @('th2') are theories (see @(see theories)).  To each of
 the arguments there corresponds a runic theory.  This function returns the
 intersection of those two runic @(see theories), represented as a list and
 ordered chronologically.</p>

 <p>This ``function'' is actually a macro that expands to a term mentioning the
 single free variable @(tsee world).  When theory expressions are evaluated by
 @(tsee in-theory) or the @(':')@(tsee in-theory) hint, @(tsee world) is bound
 to the current ACL2 @(see world).</p>")

(defxdoc intersectp
  :parents (lists acl2-built-ins)
  :short "Test whether two lists intersect"
  :long "@({
  General Forms:
  (intersectp l1 l2)
  (intersectp l1 l2 :test 'eql)   ; same as above (eql as equality test)
  (intersectp l1 l2 :test 'eq)    ; same, but eq is equality test
  (intersectp l1 l2 :test 'equal) ; same, but equal is equality test
 })

 <p>@('(Intersectp l1 l2)') returns @('t') if @('l1') and @('l2') have a @(tsee
 member) in common, else it returns @('nil').  The optional keyword,
 @(':TEST'), has no effect logically, but provides the test (default @(tsee
 eql)) used for comparing members of the two lists.</p>

 <p>The @(see guard) for a call of @('intersectp') depends on the test.  In all
 cases, both arguments must satisfy @(tsee true-listp).  If the test is @(tsee
 eql), then one of the arguments must satisfy @(tsee eqlable-listp).  If the
 test is @(tsee eq), then one of the arguments must satisfy @(tsee
 symbol-listp).</p>

 <p>See @(see equality-variants) for a discussion of the relation between
 @('intersectp') and its variants:</p>

 <blockquote><p>@('(intersectp-eq x lst)') is equivalent to @('(intersectp x
 lst :test 'eq)');</p>

 <p>@('(intersectp-equal x lst)') is equivalent to @('(intersectp x lst :test
 'equal)').</p></blockquote>

 <p>In particular, reasoning about any of these primitives reduces to reasoning
 about the function @('intersectp-equal').</p>

 @(def intersectp-equal)")

(defxdoc introduction-to-a-few-system-considerations
  :parents (introduction-to-the-theorem-prover)
  :short "The mechanics of interaction with the theorem prover"
  :long "<p>ACL2 is implemented in Common Lisp.  There are many different
 Common Lisps and they differ in details relating to interacting with the
 system.  We sometimes refer to the host Common Lisp as ``raw Lisp.''  The new
 user is advised not to operate in raw Lisp as it is possible to, say, redefine
 ACL2 system facilities like @('defthm').</p>

 <p>Most people use Emacs (see @(see Emacs) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>) or
 the ACL2 Sedan (Eclipse) interface (see @(see ACL2-Sedan) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>).
 They provide protection against certain common mistakes, e.g., trying to edit
 a block of input text after the operating system has buffered it up and sent
 it to the Lisp reader which is parsing it as you type.  More on this below.
 In addition, the Sedan provides helpful syntax checking and a disciplined
 approach to the stack of lemmas generated by The Method.  But the variety of
 interfaces to the variety of Lisps mean that there is great variation in what
 one must type to interact with ACL2.</p>

 <p>The best example is perhaps trying to interrupt a running proof.  For most
 host Common Lisp implementations, if you are typing directly to the Common
 Lisp process, then you can interrupt a computation by typing ``ctrl-c'' (hold
 down the Control key and hit the ``c'' key once).  If you are typing to an
 Emacs process which is running ACL2 in a shell buffer, you should type ctrl-c
 ctrl-c.  If you are running the ACL2 Sedan, you can use the <i>Interrupt
 Session</i> button on the tool bar.  The environment you enter when you
 interrupt depends on various factors and normally, you will be put back into
 the top level ACL2 command loop.  If not, then you may be in a Lisp break, and
 you can probably get back into the ACL2 command loop by using an ``abort''
 command that depends on the host Common Lisp (e.g., @(':q') for GCL and CCL).
 You can usually determine what environment you're in by paying attention to
 the prompt, which we discuss below.</p>

 <p>The ACL2 ``interactive loop'' is called @(tsee LP) (<see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>)
 and is generally invoked automatically from your Common Lisp when you start up
 the ACL2 process.  @('LP') is just a special case of an ACL2 function called
 @(tsee LD) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>, which the user can call from within the ACL2
 interactive loop to enter the loop recursively.  New users don't have to know
 this except that it helps explain why some commands have the string
 ``@('-ld-')'' in their names!</p>

 <p>ACL2 presents itself as a ``read-eval-print'' loop: you're repeatedly
 prompted for some type-in, which is read, evaluated, and may cause some
 printing.  The prompt tells you something about ACL2's state.  In the standard
 environment, the prompt is</p>

 @({
  ACL2 !>
 })

 <p>The ``@('ACL2')'' tells you that the symbols you use in your command are
 those defined in the standard ACL2 namespace (or, in the jargon of Lisp, the
 ``current package,'' see @(see current-package) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>).
 You could create a new namespace (see @(see defpkg) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>)
 and set the current package to it (see @(see in-package) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>).
 The next part of the prompt above
 (``@('!')''), the exclamation mark) tells you that before ACL2 evaluates your
 type-in it will check to see whether @(tsee guard)s (<see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>)
 are respected, i.e., whether the functions used in your command are being
 supplied arguments in their ``expected domains.''  If evaluation is allowed by
 the guards, it proceeds exactly according to the ACL2 axioms; if evaluation is
 not allowed, an error is signaled.  ACL2 event commands check their arguments
 thoroughly at run-time, regardless of Lisp's notion of ``expected
 domains.''</p>

 <p>If the exclamation mark is missing from the prompt,</p>

 @({
  ACL2 >
 })

 <p>then evaluation occurs strictly according to the ACL2 axioms, without
 regard for any declared guards.</p>

 <p>You can switch between these two prompts by typing</p>

 @({
  ACL2 !>:set-guard-checking nil
 })

 <p>to turn guard checking off and</p>

 @({
  ACL2 >:set-guard-checking t
 })

 <p>to turn it on.  Try typing @('(car 7)') to each prompt.</p>

 <p>If there is a ``@('p')'' in the prompt,</p>

 @({
  ACL2 p!>
 })

 <p>with or without the exclamation mark:</p>

 @({
  ACL2 p>
 })

 <p>it means you are in @(':')@(tsee program) (<see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>)
 mode rather than @(':')@(tsee logic) (<see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>)
 mode.  In @(':program') mode, @('defun') just defines Common Lisp programs
 that you can evaluate, but it adds no axioms and you cannot use such defined
 functions in theorems or invoke @('defthm').  @(':Program') mode is often used
 to prototype a model.</p>

 <p>Most commands are just typical parenthesized Lisp expressions, like</p>

 @({
  ACL2 !>(defthm rev-rev
           (implies (true-listp x)
                    (equal (rev (rev x)) x)))
 })

 <p>but some are typed as keywords followed by a certain number of
 arguments.</p>

 <p>For example, to undo the last event you may type</p>

 @({
  ACL2 !>:u
 })

 <p>or to undo back through the introduction of @('rev') you may type</p>

 @({
  ACL2 !>:ubt rev
 })

 <p>The first is equivalent to evaluating @('(u)') and the second is equivalent
 to evaluating @('(ubt 'rev)').  See @(see keyword-commands) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>.
 So if you see a sentence like ``to turn on the break rewrite facility, execute
 @(':brr t'),'' we mean type</p>

 @({
  ACL2 !>:brr t
 })

 <p>or equivalently</p>

 @({
  ACL2 !>(brr t)
 })

 <p>If you see a prompt that doesn't look like those above you are probably not
 typing commands to the standard ACL2 read-eval-print loop!  If you've somehow
 called @('LD') recursively, the prompt ``gets deeper,'' e.g.,</p>

 @({
  ACL2 !>>
 })

 <p>and you can pop out one level with @(':')@(tsee q) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>
 (for ``quit'') or pop to the outermost ACL2 loop with @(':')@('abort!') <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>.  If you are in the outermost call of the
 ACL2 interactive loop and you type @(':q'), you pop out into raw lisp, which
 carries some risk; see @(see q).  The prompt in raw Lisp is generally
 different from the ACL2 prompt but that is outside our our control and varies
 from Lisp to Lisp.  See @(see prompt).  To get back into the ACL2 interactive
 loop from raw lisp, evaluate @('(LP)').</p>

 <p>If you see a prompt that looks like an ACL2 prompt but has a number in
 front of it, e.g.,</p>

 @({
  1 ACL2 >
 })

 <p>then you're talking to the break rewrite facility (and you are 1 level deep
 in the example above).  Presumably at earlier time in this session you enabled
 that facility, with @(':brr t'), installed a monitor on some rule, invoked the
 prover, entered the break, and forgot.  Everything you have done (e.g., lemmas
 you might have proved with @('defthm')) inside that break will be lost when
 you exit the break.</p>

 <p>Since the break rewrite facility is ``ours'' we can tell you how to exit
 it!  To exit our breaks and return to the top-level ACL2 loop, execute
 @(':')@(tsee abort!).</p>

 <p>If you discover you've been working in a @('brr') break, exit, turn off the
 break facility with @(':brr nil'), and redo whatever @('defun')s and
 @('defthm')s you did while in that break.</p>

 <p>Users of the Emacs interface may occasionally type commands directly in the
 @('*shell*') buffer running ACL2.  This can be ``dangerous'' for two reasons.
 One is that if you type an event, like a @('defun') or @('defthm'), directly
 to the shell, it will not be recorded in your ``script'' buffer and you may
 forget it in your final script.  The other is that if you attempt to edit a
 multi-line command on any but the most recent line, e.g., to correct the
 spelling of @('defthm') below after you've typed the ``@('(implies (true-listp
 x)')'' you will confuse the Lisp parser because it has already read
 ``@('(defthm rev-rev')''.</p>

 @({
  ACL2 !>(defthm rev-rev
           (implies (true-listp x)
 })

 <p>This usually provokes the raw Lisp to enter a low level error break from
 which you must abort, possibly reenter the ACL2 loop, and re-type the
 corrected command from scratch.</p>

 <p>Another common mistake when using interfaces other than the ACL2 Sedan is
 to type an ill-formed ACL2 expression containing dots or commas, which also
 often provokes a break into the raw Lisp's error handler.</p>

 <p>The fundamental lesson is that you should pay attention to the prompt and
 learn what the different prompts mean &mdash; or use the ACL2 Sedan.</p>

 <p>If you have been working your way through the tutorial introduction to the
 theorem prover, use your browser's <b>Back Button</b> now to return to @(see
 introduction-to-the-theorem-prover).</p>")

(defxdoc introduction-to-apply$
  :parents (apply$)
  :short "Background knowledge on how to use @(tsee apply$), @(tsee
 defwarrant), etc."
  :long "

  <h3>Background and Organization</h3>

  <p>@('Apply$') is the ACL2 version of LISP's @('apply') function.  It takes a
  ``function'' and a list of argument values, applies the function to the
  arguments, and returns the result.  For example, @('(apply$ 'expt (list 2
  8))') returns 256.</p>

  <p>A good introduction to the basic ideas and challenges of adding
  @('apply$') to ACL2 is the paper <a
  href='http://www.cs.utexas.edu/users/kaufmann/papers/apply/index.html'>``Limited
  Second-Order Functionality in a First-Order Setting''</a> by Matt Kaufmann
  and J Strother Moore, <i>Journal of Automated Reasoning</i>, Springer,
  <b>64</b>, pp 391-422, 2018.  We refer to the paper simply as ``the paper.''
  Some aspects of the paper are no longer accurate because the implementation
  of @('apply$') has matured since 2018.  But as a basic introduction, rather
  than a reference guide or user's manual, the paper is a good place to start.
  It provides motivations and challenges, succinct and precise definitions of
  relevant concepts, lots of examples, a model and meta-level proof that the
  extended theory is consistent, and a discussion of the limitations and of
  related work.  The model described in the paper is illustrated concretely in
  the certified books under @('books/projects/apply-model/').  See the
  @('README') file there.</p>

  <p>The current documentation topic takes a slightly more informal approach
  but covers much of the same ground.  In particular, after some preliminary
  remarks we coach you through a few simple simple exercises involving
  @('apply$') and related concepts.  During these exercises we draw your
  attention to some basic lessons to keep in mind.  At the end of this topic we
  list some simple challenge problems.</p>

  <p>This topic links to reference-level documentation for @(tsee apply$) and
  those other concepts.  But if you are just getting started with @('apply$')
  we recommend that you work your way through this topic, including doing the
  examples described below, without following all the links.</p>

  <h3>Challenges and Basic Solutions</h3>

  <p>The unreachable goal of this work is to allow the ACL2 user to pass
  `functions' as objects and to apply them.  That goal is unreachable because
  ACL2 remains a first order system.  However, we can identify a certain
  syntactic class of ordinary ACL2 objects, called the `@(see tame)
  functions' (which are in fact <i>not</i> functions but are merely symbols and
  list expressions) and we can allow names of functions with certain tameness
  properties to be passed around and used as functions.</p>

  <p>By the way, in this documentation topic we tend to display certain symbols
  sometimes in uppercase and sometimes in lowercase.  They denote the same
  symbol.  But we use uppercase when we're using the symbol as a quoted
  constant to be passed to @('apply$') and we use lowercase when we're using
  the symbol as a function symbol in a term.</p>

  <p>``Tameness'' imposes strict rules on how functional arguments are used.
  We'll discuss it further below.</p>

  <p>The fundamental question raised by @('apply$') is ``How can @('apply$')
  know the correspondence between an ordinary ACL2 object, like a symbol or a
  list, and the ACL2 function the user means to apply?''  For example, if the
  user defines the function @('my-append'), how can @('apply$') know that
  @('(apply$ 'MY-APPEND (list a b))') should expand to @('(my-append a b)')?</p>

  <p>The ACL2 primitives can be built in.  The logical definition of @('apply$')
  includes a big case split that recognizes about 800 ACL2 primitives, so that
  for example:</p>

  @({(apply$ 'car (list a)) = (car a)})

  <p>and</p>

  @({(apply$ 'assoc-equal (list a b)) = (assoc-equal a b).})

  <p>But user-defined functions are problematic because once @('apply$') has been
  defined in the ACL2 sources it cannot be extended to handle new symbols.</p>

  <p>Intuitively, if you have defined the @('n')-ary function @('foo') then you
  would expect @('(apply$ 'foo (list a1...an))') to be @('(foo a1...an)').  One
  way to arrange that might be to leave @('apply$') undefined on the symbol
  @('foo') but to assume, as by a new axiom or hypothesis,</p>

  @({
  forall a1...an : (apply$ 'foo (list a1...an)) = (foo a1...an).
  })

  <p>It will turn out that using new axioms for this purpose is a bad idea.
  Hiding the link between @('apply$') and new symbols in axioms raises a
  problem with ACL2's notion of @(tsee LOCAL).  This is called ``the @('LOCAL')
  problem'' and we illustrate it later in this doc topic.  But for that reason,
  the suppositions extending @('apply$') will take the form of hypotheses to be
  added to conjectures in which the behavior of @('apply$') on new symbols is
  important.  These hypotheses are called ``@(tsee warrant)s.''</p>

  <p>Warrant (Merriam-Webster): (noun) a commission or document giving
  authority to do something....</p>

  <p>In our case, a warrant for @('fn') gives @('apply$') permission to apply
  @('fn') under some circumstances, by asserting a universally quantified
  conditional equality about @('apply$')'s behavior on @(''fn'). It also tells
  @('apply$') and the @(see tame)ness predicates things like how many arguments
  @('fn') takes and how it uses them by asserting the @(tsee badge) of
  @(''fn').  The @('badge') of @('fn') is an ACL2 object that contains various
  tokens interpretable by @('apply$') and the tameness predicates.</p>

  <p>But there is a fundamental logical problem: it is not always possible to
  satisfy such suppositions. There may be no way that @('apply$') could handle
  @('fn').  An example of a @('fn') for which that hypothesis is unsatisfiable
  is</p>

  @({
  (defun russell (x y) (not (apply$ x (list y y)))).
  })

  <p>This definition of @('russell') is not recursive: it does not call itself.
  So this definition is admissible.  But if we had a warrant for @('apply$')
  and that @('warrant') were as simple as</p>

  @({forall x,y : (apply$ 'russell (list x y)) = (russell x y)})

  <p>then we would have this classical problem with self-reference:</p>
  @({
  (russell 'russell 'russell)
  =                                      {def russell}
  (not (apply$ 'russell (list 'russell 'russell)))
  =                                      {warrant russell}
  (not (russell 'russell 'russell))
  })

  <p>which is contradictory.</p>

  <p>This problem is addressed by introducing the notion of ``tameness.''
  Tameness is a syntactic property of terms and functions that implies that it
  is ok to ``extend'' @('apply$') to handle them.</p>

  <p>It should be pretty clear that if the user defines an ACL2 function that
  in no way depends on @('apply$'), e.g., a function like:</p>

  @({(defun sq (x) (* x x))})

  <p>then the hypothesis</p>

  @({
  forall x : (apply$ 'SQ (list x)) = (sq x)
  })

  <p>is satisfiable: we could have introduced @('sq') before @('apply$') and
  then defined @('apply$') in the first place to handle that particular
  symbol.</p>

  <p>@('Sq') is a particularly simple example of a tame function.  One
  challenge in this work has been to extend the notion of tameness so that it
  includes a lot of what a normal ACL2 programmer might want in @('apply$')
  while maintaining the soundness of the resulting theory.</p>

  <p>For example, consider the following function, which maps a given function
  over a list and collects the results.</p>

  @({
  (defun my-collect$ (fn lst)
    (if (endp lst)
        nil
        (cons (apply$ fn (list (car lst)))
              (my-collect$ fn (cdr lst)))))
  })

  <p>Our definition of tameness considers <tt>(my-collect$ 'SQ lst)</tt> to be a
  tame expression, even though @('my-collect$') calls @('apply$').  The reason we
  can allow this is that in this particular call of @('my-collect$') the function
  to be applied is itself tame.  But if <tt>(my-collect$ 'SQ lst)</tt> is a tame
  expression, then <tt>'(LAMBDA (LST) (MY-COLLECT$ 'SQ LST))</tt> is a tame
  function and thus</p>

  @({(my-collect$ '(LAMBDA (LST) (MY-COLLECT$ 'SQ LST)) z)})

  <p>is a tame expression.  So, for example, at the top-level of ACL2 one
  can do this:</p>

  @({
  ACL2 !>(my-collect$ '(LAMBDA (LST) (MY-COLLECT$ 'SQ LST))
                   '((1 2 3) (4 5 6) (7 8 9)))
  ((1 4 9) (16 25 36) (49 64 81))
  })

  <p>Of course, this presumes we have defined @('sq') and @('my-collect$') and have
  analyzed them to make sure they have the appropriate tameness properties.
  (Note that @('my-collect$') is not tame, but the way it uses its ``functional''
  argument is crucial to the tameness of <tt>(my-collect$ 'SQ lst)</tt>.)  To use
  @('apply$') to full advantage we need to have analyzed every relevant
  function definition so we know which arguments are treated like functions and
  whether they are used in accordance with our restrictions.  So if you're
  defining a function you intend to @('apply$') it is convenient to define it
  with the new command @(tsee defun$), which is just an ordinary @(tsee defun)
  followed by a @(tsee defwarrant) command.  If you've already defined the
  function and then realize you wish to @('apply$') it, you can call
  @('defwarrant') yourself.</p>

  <p>@('Defwarrant') analyzes a @(':')@(tsee logic) mode definition and
  produces a badge and a warrant, if possible.  Also relevant is the @(tsee
  defbadge) command which issues a badge for a function (if possible) but does
  not issue a warrant.  Its primary purpose is to allow @(':')@('program') mode
  functions to be analyzed and badged so they can be safely executed by
  @('apply$') at the top-level ACL2 loop.  But the present discussion focuses
  primarily on the logical machinery, which requires warrants.</p>

  <p>We explain further via an annotated example, starting from scratch but
  from the basic background just sketched.  For many additional examples, see
  @(see community-books) @('books/projects/apply/report.lisp') which is a
  certified book containing the examples in the paper.</p>

  <p><b>Note carefully:</b> the directory @('books/projects/apply-model/'),
  mentioned earlier in conjunction with the paper, is different from the
  directory @('books/projects/apply/') just mentioned!  The former directory
  concerns the logical foundations of @('apply$') as they stood when the paper
  was written.  The latter is more directly relevant to ACL2 users and provides
  useful lemmas about @('apply$') as it is axiomatized and implemented today.
  It also includes many example theorems.</p>

  <h3>Exercises and Lessons</h3>

  <p>To get started, fire up your ACL2 and define two ordinary ACL2 functions,
  one that squares its argument and the other that reverses its argument.  We
  show the ACL2 prompt below in front of each form we expect you to execute.</p>

  @({
  ACL2 !>(defun sq (x) (* x x))

  ACL2 !>(defun rev (x)
           (if (endp x)
               nil
               (append (rev (cdr x)) (list (car x)))))
  })

  <p><b>Lesson 0:</b> Learn about @('apply$') by reading this tutorial
  introduction.  But this tutorial mentions many undefined concepts: tameness,
  warrants, badges, ilks.  These concepts are intertwined with @('apply$') and
  warrants through mutual recursion, constraints, rewrite rules, etc..  So we
  decided not to try to define them here as we go along, though the links
  provided do provide definitive descriptions.  So please tolerate the use of
  undefined words here &mdash; we'll try to give you a sense of what they
  mean.</p>

  <p><b>Lesson 1:</b> To use @('apply$'), be sure to include the following book
  of lemmas.  These lemmas are important not just to proving theorems about
  @('apply$') but to defining functions that use @('apply$').</p>

  @({
  ACL2 !>(include-book "projects/apply/top" :dir :system)
  })

  <p><b>Lesson 2:</b> To allow @('apply$') to ``work'' on a function symbol the
  symbol must be ``warranted.''  Actually, of course, you can pass anything to
  @('apply$') and the axioms will reduce it to some value: ACL2 is untyped and
  all functions are total!  But @('apply$') won't work in the logic as you
  expect if the first argument to @('apply$') is not warranted!  (And
  @('apply$') won't work as you expect for top-level evaluation if its first
  argument is not at least badged.)  To issue warrants (and badges) for @('sq')
  and @('rev') do:</p>

  @({
  ACL2 !>(defwarrant sq)

  ACL2 !>(defwarrant rev)
  })

  <p>@(tsee Defwarrant) checks that its argument, <i>fn</i>, is a defined
  function symbol that satisfies certain restrictions on how it uses its
  arguments, restrictions that enable us to define the tameness predicates and
  that allow @('apply$') to ``work'' without causing logical contradictions.
  @('Defwarrant') causes an error if <i>fn</i> does not obey our rules.  But if
  @('defwarrant') does not cause an error it produces a ``badge'' for <i>fn</i>
  that describes which formals are treated as ``functions.''  Henceforth, we'll
  say such formals have ``@(see ilk)'' @(':FN').  In addition to computing a
  badge, non-erroneous calls of @('defwarrant') introduce a &ldquo;@(tsee
  warrant) function&rdquo; for <i>fn</i>.  The warrant function for <i>fn</i>
  is a 0-ary function named @('apply$-warrant-')<i>fn</i>.  A call of the
  warrant function, i.e., the term @('(apply$-warrant-')<i>fn</i>@(')') is
  called the &ldquo;warrant&rdquo; for <i>fn</i> and if the warrant for
  <i>fn</i> is included among the hypotheses of a conjecture then @('(apply$
  '')<i>fn</i>@(' (list a1 ... an))') can expand to @('(')<i>fn</i>@(' a1
  ... an)'), provided the @('ai') meet the tameness requirements required by
  <i>fn</i>'s badge.</p>

  <p><b>Lesson 3:</b> We'll say more about tameness, badges, and warrants
  later.  You already know that warrants can only be issued for @(':logic')
  mode functions because the function symbol is used as a function in the
  logical definition of the warrant.  But you might as well learn four major
  limitations of @('apply$'):
  (i) @('Apply$') does not take @(tsee STATE) or @(see stobj) arguments and so
  cannot call any function that takes @('STATE') or @('stobj') arguments.  (ii)
  @('Apply$') cannot call a function whose measure, well-founded relation, or
  domain predicate depends on @('apply$'). (iii) @('Apply$') cannot call a
  function that itself uses @('apply$') unless that function's measure is a
  natural number or a lexicographic combination of naturals formed with
  @('llist') as defined in the Community Books at @('books/ordinals/'). (iv)
  @('Apply$') cannot call a function that itself uses @('apply$') if that
  function was defined mutually recursively.  Another way of saying all this is
  that @('defwarrant') will cause an error if you try to warrant a function
  violating (i), (ii), (iii) or (iv).</p>

  <p><b>Lesson 4:</b> If you want to define a function and immediately call
  @('defwarrant') on it you can use the handy macro @('defun$').  We'll use
  @('defun$') freely below.</p>

  <p><b>Lesson 5:</b> You can define functions that take warranted
  ``functions'' as arguments and @('apply$') them.  Here is a function that
  applies its first argument to every element of its second argument and
  collects the results.  We sometimes call functions like @('my-collect$')
  ``mapping functions'' because they map another function over some range.  We
  would call them ``functionals'' except that suggests ACL2 is higher-order and
  it is not!  So we most often call them @(see scion)s of @('apply$').  In
  ordinary English usage, a ``scion'' is a descendant of an important family or
  individual; our scions are ``descendants'' of @('apply$') and inherit its
  power and restrictions.</p>

  @({
  ACL2 !>(defun$ my-collect$ (fn lst)
           (if (endp lst)
               nil
               (cons (apply$ fn (list (car lst)))
                     (my-collect$ fn (cdr lst)))))
  })

  <p>In this definition, the first argument has ilk @(':FN') because it is used
  exclusively as a ``function:'' it reaches the first argument of @('apply$')
  and is untouched otherwise.  The second argument has ilk @('NIL') and we say
  it's ``ordinary.''  It is <i>never</i> used as a function.</p>

  <p>Note: We define @('my-collect$') with @('defun$') simply to illustrate
  @('defun$').  Unless we mean to pass @('my-collect$') to @('apply$') or to
  some scion in the future, there is no reason to have a warrant for
  @('my-collect$').  Had we defined @('my-collect$') with the ordinary
  @('defun') and realized later that we want to pass @(''MY-COLLECT$') into a
  slot of ilk @(':FN'), we could get a warrant for @('my-collect$') by calling
  @('(defwarrant my-collect$)').</p>

  <p>Actually, the function @('collect$') is pre-defined in ACL2 and behaves
  like @('my-collect$').  We chose to introduce @('my-collect$') simply to
  illustrate that new scions can be introduced and used.  Here's another useful
  pre-defined scion.  You won't need to define it in your ACL2 session to use
  it.</p>

  @({
  (defun$ always$ (fn lst)
    (if (endp lst)
        t
        (and (apply$ fn (list (car lst)))
             (always$ fn (cdr lst)))))
  })

  <p>It checks that every element of @('lst') satisfies its @(':FN') argument
  @('fn').</p>

  <p>The reason that both @('collect$') and @('always$') are pre-defined is
  that they are part of the support for the @(tsee loop$) statment.</p>

  <p><b>Lesson 6:</b> You can run scions on warranted function symbols:</p>

  @({
  ACL2 !>(my-collect$ 'SQ '(1 -2 3 -4))
  (1 4 9 16)

  ACL2 !>(my-collect$ 'rev '((1 2 3) (4 5 6) (7 8 9)))
  ((3 2 1) (6 5 4) (9 8 7))
  })

  <p>You might wonder why you can run @('my-collect$') on @(''SQ') &mdash; which
  evaluates @('apply$') on @(''SQ') &mdash; without explicitly acknowledging
  the warrant that links @('(apply$ 'SQ (list a))') to @('(sq a)').  The reason
  is that evaluation in ACL2's top-level read-eval-print loop assumes all
  existing warrants are provided.  Warrants only become important when we start
  dealing with proofs.</p>

  <p><b>Lesson 7:</b> You can run scions on tame quoted @('LAMBDA') objects.
  These @('LAMBDA') objects can even include calls of scions, provided
  they are tame.</p>

  @({
  ACL2 !>(my-collect$
               (lambda$ (x) (CONS 'SQUARES (MY-COLLECT$ 'SQ x)))
               '((1 2 3) (4 5 6)))
  ((SQUARES 1 4 9) (SQUARES 16 25 36))
  })

  <p>Note that the ``function symbols'' in the ``body'' of a quoted @('LAMBDA')
  object may reach @('apply$') as the @('LAMBDA') object is applied.</p>

  <p>@('LAMBDA') objects are just quoted list expressions that start with the
  symbol @('LAMBDA') and look like lambda-expressions.  But quoted @('LAMBDA')
  objects have to have fully translated bodies and meet other restrictions so
  @('apply$') can interpret them.  You cannot use macros like @('+') or
  @('cond') and must you quote all constants.  We urge you not to try to type
  quoted @('LAMBDA') objects by hand!  Instead, we provide a macro, @(tsee
  lambda$), that allows you to write lambda expressions in untranslated
  form.</p>

  <p><b>Lesson 8:</b> There are three very similar looking but very different
  notions used in this documentation: lambda expressions, @('LAMBDA') objects,
  and @('lambda$') expressions.  Read carefully!  See @(tsee lambda) for some
  definitions and disambiguation help.  The @('LAMBDA') objects reaching
  @('apply$') must be fully translated (and tame) to be handled correctly.  The
  special macro @('lambda$') will translate for you.</p>

  @({
  ; Don't type quoted LAMBDA objects like this!
  ACL2 !>(my-collect$ '(LAMBDA (x)
                         (IF (< x '0) (BINARY-* '10 x) (SQ x)))
                      '(1 -2 3 -4))
  (1 -20 9 -40)

  ; Type this instead!
  ACL2 !>(my-collect$ (lambda$ (x)
                         (if (< x 0) (* 10 x) (sq x)))
                      '(1 -2 3 -4))
  (1 -20 9 -40)
  })

  <p><b>Lesson 9:</b> Almost all ACL2 primitives are known to @('apply$').  For
  a complete list of the built-ins evaluate</p>

  @({
  (append '(BADGE TAMEP TAMEP-FUNCTIONP SUITABLY-TAMEP-LISTP
                  APPLY$ EV$)
          (strip-cars *badge-prim-falist*))
  })

  <p>You can freely use these ACL2 primitives with @('apply$') and in your
  @('lambda$') expressions, without warrants.</p>

  <p><b>Lesson 10:</b> You can prove and use theorems about scions.</p>

  @({
  ACL2 !>(defthm my-collect$-append
           (equal (my-collect$ fn (append a b))
                  (append (my-collect$ fn a)
                          (my-collect$ fn b))))

  ACL2 !>(thm (equal (my-collect$ (lambda$ (x) (* x x))
                                  (append c d))
                     (append (my-collect$ (lambda$ (x) (* x x)) c)
                             (my-collect$ (lambda$ (x) (* x x)) d))))
  })

  <p>Notice that the lemma @('my-collect$-append') talks about an arbitrary
  @('fn').  The definition of @('apply$') is completely irrelevant to this
  theorem!  Once @('my-collect$-append') has been proved can be instantiated
  with anything for @('fn').  This is demonstrated when the @('thm') above is
  proved: the proof is just to rewrite with @('my-collect$-append').  Notice
  that the only function being @('apply$')'d in the @('thm') above is the
  primitive multiplication function, which is built into apply$.</p>

  <p><b>Lesson 11:</b> But when your theorems depend on the behavior of
  @('apply$') on particular user-defined functions, you will need to provide
  hypotheses stipulating the behavior of @('apply$') on those values.  Those
  hypotheses are the <i>warrants</i> for the (non-primitive) function symbols
  involved.  Here is an example: Recall the function @('sq') defined and
  warranted above.  We might wish to prove that if @('lst') is a list of
  integers then @('(my-collect$ 'SQ lst)') is a list of natural numbers.  We
  can use @('always$') to express the notions of ``list of integers'' and
  ``list of naturals.''  We could try to state the conjecture this way:</p>

  @({
  ACL2 !>(thm (implies (always$ 'INTEGERP lst)
                       (always$ 'NATP (my-collect$ 'SQ lst)))).
  })

  <p>But the attempt to prove that formula will fail because it depends on the
  fact that the @('sq') of an integer is a natural <i>and on the assumption
  that</i> @('(apply$ 'SQ (list x))') <i>is</i> @('(sq x)').  That assumption
  is what the <i>warrant</i> for @('sq') tells us.  Thus, the warrant for
  @('sq') is required as a hypothesis!  The following theorem can be
  proved.</p>

  @({
  ACL2 !>(defthm all-natp-collect$-sq
           (implies (and (warrant sq)
                         (always$ 'INTEGERP lst))
                    (always$ 'NATP (collect$ 'SQ lst))))
  })

  <p>Note that we don't need to provide warrants for @('integerp') or @('natp')
  because they are ACL2 primitives and thus built into the behavior of
  @('apply$').  But we must provide the warrant for @('sq') because we know the
  proof depends on @('(apply$ 'sq (list x1 ...))') simplifying to @('(sq
  x1)').</p>

  <p>The macro form @('(warrant f1 ... fk)') expands to the conjunction of the
  warrants for the @('fi')s.  That is</p>
  @({
  (warrant f1 ... fk)
  =
  (and (apply$-warrant-f1)
       ...
       (apply$-warrant-fk)).
  })

  <p>If you attempt a proof and it fails, and you see among the checkpoints
  terms of the form @('(apply$ 'fn (list a1 ... an))'), then you probably
  forgot to call @('defwarrant') on @('fn') and @('apply$') doesn't know what
  to do with that symbol!  If, on the other hand, you see a @(see
  forcing-round) checkpoint that is attempting to prove a warrant, like
  @('(apply$-warrant-fn)'), then you probably forgot to add the warrant for
  @('fn') to the hypotheses of the conjecture you're trying to prove.</p>

  <p><b>Lesson 12:</b> Warrants solve the ``@('LOCAL') problem.''  Imagine the
  trouble we'd be in if the theorem above did not require a warrant on @('sq').
  We could get away with this:</p>

  @({
  (encapsulate nil
    (local (defun sq (x) (* x x)))
    (defthm unwarranted-all-natp-collect$-sq
      (implies (always$ 'INTEGERP lst)
               (always$ 'NATP (collect$ 'SQ lst)))))

  (defun sq (x) (* x x x))

  (thm (implies (always$ 'INTEGERP lst)
                (always$ 'NATP (collect$ 'SQ lst))))
  })

  <p>This would be a disaster because the final @('thm') is invalid since
  @('(sq -2)') here is @('-8') and yet the @('thm') is trivially proved by
  appealing to the unwarranted theorem exported from the encapsulate.</p>

  <p>If we could prove the unwarranted theorem we could export it because it
  does not mention or depend on the locally defined function @('sq'), it just
  mentions the constant symbol <tt>'SQ</tt>.  Fortunately, we cannot actually
  prove the unwarranted version of the theorem because there is no <i>a
  priori</i> connection between @('(apply$ 'SQ (list x))') and @('(sq x)').
  And if we add the warrant for @('sq') to the @('defthm') in the encapsulate
  we can prove the theorem but then we cannot export it because the warrant
  ancestrally depends on locally defined function @('sq').</p>

  <p><b>Lesson 13:</b> While we may have given the impression that we've
  provided a convenient fragment of second-order functionality in ACL2 its
  limitations will annoy you!  For example, when ACL2 tries to use the
  lemma</p>

  @({
  (defthm all-natp-collect$-sq
    (implies (and (warrant sq)
                  (always$ 'INTEGERP lst))
             (always$ 'NATP (collect$ 'SQ lst))))
  })

  <p>it just employs its usual first-order matching algorithm.  Thus, the lemma
  won't apply to</p>

  @({
  (always$ 'NATP (collect$ (lambda$ (x) (* x x)) lst))
   })

  <p>because the constant symbol <tt>'SQ</tt> is not the same as the constant
  list generated by translating @('lambda$') expression,
  <tt>@(''(LAMBDA (X) (BINARY-* X X))')</tt>, even though they are equivalent
  if understood as functions.  See the discussion at @(tsee fn-equal).</p>

  <p><b>Lesson 14:</b> Recall Lesson 0!  Before you start to use @('apply$')
  outside of this simple demo script, we advise you to read the documentation
  for @('apply$').</p>

  <p><b>An Advanced Lesson:</b> We conclude this tutorial by defining one of
  the most useful scions and proving a couple of theorems illustrating its
  flexibility: @('foldr').</p>

  @({
  ACL2 !>(defun$ foldr (lst fn init)
           (if (endp lst)
               init
               (apply$ fn
                       (list (car lst)
                             (foldr (cdr lst) fn init)))))
  })

  <p>Note that @('foldr') maps over the list in its first argument, applying
  its second argument to two things: successive elements of the list and the
  result of recursively calling itself on the rest of the list.  It returns its
  third argument when the list is empty.</p>

  <p>When its functional argument is @('CONS') @('foldr') is just the
  concatenation of its other two arguments:</p>

  @({
  ACL2 !>(defthm foldr-cons
           (equal (foldr x 'CONS y)
                  (append x y)))
  })

  <p>We do not need a warrant for @('cons') because it is built into
  @('apply$').  In fact, the built-ins don't have warrants but if you
  unnecessarily list a primitive in a @('warrant') expression, like @('(warrant
  foldr cons)'), it just ignores the primitives that are built into
  @('apply$').</p>

  <p>By supplying a certain @('lambda') expression we can use @('foldr') to
  reverse its first argument:</p>

  @({
  ACL2 !>(defthm foldr-can-be-rev
           (implies (warrant foldr)
                    (equal (foldr x
                                  (lambda$ (x y)
                                     (FOLDR y 'CONS (CONS x nil)))
                                  nil)
                           (rev x))))
  })

  <p>Note that the @('lambda$') expression calls @('FOLDR').  Because of this,
  we must provide the warrant for @('foldr') since that inner @('foldr') will
  be applied by the outer @('foldr').  This illustrates an important point made
  in Lesson 7 above: scions can apply other scions, including themselves, as
  long as the applications are tame.</p>

  <h3>Some Practice Problems</h3>

  <p>There is no better way to learn than to practice.  So here are a few
  challenge problems.  The answers can be found in
  @('books/projects/apply/answers-to-doc-intro-to-apply.lisp').</p>

  <p><b>Problem 1</b>: Assume @('fn') is a binary relation.  Define
  @('(insert$ e lst fn)') to insert @('e') into the list @('lst') in front of
  the first element, @('d'), in @('lst') such that @('(fn e d)') is true.</p>

  <p><b>Problem 2</b>: Define @('(sort$ lst fn)') to be an insertion sort
  algorithm for the binary relation @('fn'), e.g., to successively insert each
  element into the recursively sorted remaining elements.  (Note: There is no
  assurance that @('sort$') will actually produce a list ordered by @('fn')
  because we don't know that @('fn') is an ordering relation.)</p>

  <p><b>Problem 3</b>: Study the four examples below, which illustrate perhaps
  surprising properties of our ``insertion sort'' function.  (If your
  definitions don't have these properties you should back up and redefine your
  functions as we vaguely described above!)</p>

  @({
  (defthm examples-of-sort$
    (and (equal (sort$ '(1 3 -7 0 23) '<)
                '(-7 0 1 3 23))
         (equal (sort$ '(1 3 -7 0 23)
                       (lambda$ (x y) t))
                '(1 3 -7 0 23))
         (equal (sort$ '(1 3 -7 0 23)
                       (lambda$ (x y) nil))
                '(23 0 -7 3 1))
         (equal (sort$ '(1 a 2 x b 3 4 y c)
                       (lambda$ (x y) (symbolp x)))
                '(a x b y c 4 3 2 1)))
    :rule-classes nil)
  })

  <p><b>Problem 4</b>: Prove the following theorem suggested especially by the
  last example above.  To state this theorem we first introduce the familiar
  reverse function, @('rev').</p>

  @({
  (defun rev (x)
    (if (endp x)
        nil
        (append (rev (cdr x))
                (list (car x)))))
  })

  <p>and we use the pre-defined function @('(when$ fn lst)') which computes the
  elements of @('lst') satisfying the unary-function @('fn'), in the order in
  which they occur, e.g., @('(when$ '(1 a 2 b) 'symbolp)') is @(''(a b)').</p>

  <p>Prove</p>

  @({
  (defthm sort$-lambda-symbolp
    (implies (true-listp lst)
             (equal (sort$ lst (lambda$ (x y) (symbolp x)))
                    (append (when$ 'symbolp lst)
                            (rev
                              (when$
                                (lambda$ (x y) (not (symbolp x)))
                                lst))))))
  })

  <p>Lemmas will be needed.</p>

  <p><b>Problem 5</b>: Define @('(orderedp$ lst fn)') to check whether @('fn')
  holds between each adjacent pair of elements in @('lst').  Test your function
  with</p>

  @({
  (defthm examples-of-orderedp$
    (and (orderedp$ '(1 3 5 7) '<)
         (not (orderedp$ '(1 3 3 5 7) '<)))
    :rule-classes nil)
  })

  <p><b>Problem 6</b>: You might hope that @('(orderedp$ (sort$ lst fn) fn)')
  is a theorem.  But it is not as is easily shown by the example
  @('(orderedp$ (sort$ '(3 1 5 3 7) '<) '<)').  If you try to prove the
  conjecture and inspect the output you'll see that the proof fails because we
  do not know that @('(or (fn x y) (fn y x))') is true.  That is, we don't know
  that @('fn') is <i>Strongly Connected</i>.  How could we, since the
  conjecture is claimed for all @('fn')?</p>

  <p>Unfortunately, it is awkward to state that @('fn') is a strongly connected
  relation in ACL2's first-order quantifier-free language.  This is a good
  example of the limitations of ACL2's support for second-order functions!</p>

  <p>But we can prove versions of the conjecture for concrete strongly
  connected @('fn')s.  The relation named @('before-dayp'), below, is strongly
  connected, as demonstrated by the events following its definition.</p>

  <p>Carry out these events.</p>

  @({
  (defun beforep (x y lst)
    (if (and (member x lst)
             (member y lst))
        (member y (member x lst))
        t))

  (defun before-dayp (x y)
    (beforep x y '(mon tue wed thu fri sat sun)))

  (defthm before-dayp-strongly-connected
    (implies (not (before-dayp x y))
             (before-dayp y x)))

  (in-theory (disable before-dayp))
  })

  <p>Now, prove the version of @('(orderedp$ (sort$ lst fn) fn)') for the
  instance in which @('fn') is @(''before-dayp').</p>")

(defxdoc introduction-to-hints
  :parents (introduction-to-the-theorem-prover)
  :short "How to provide hints to the theorem prover"
  :long "<p>We assume you've read @(see introduction-to-rewrite-rules-part-1),
 @(see introduction-to-key-checkpoints), and @(see
 introduction-to-the-database).</p>

 <p>You may give the theorem prover a hint that is specific to a particular
 subgoal generated during a proof attempt.  Of course, you learn the name of
 the subgoal by inspecting the key checkpoints or other proof output.  You are
 not expected to anticipate the need for hints at specific subgoals; instead,
 you usually deduce that a hint is required because the subgoals is not proved
 but you see that existing rules and context make it provable.</p>

 <p>The most common hint is to enable and/or disable a particular rule on some
 particular subgoal.</p>

 <code>
 (defthm <i>name</i>
         <i>formula</i>
         :hints (("Subgoal *1/3.2''" :in-theory (disable nth-nthcdr))))
 </code>

 <p>The hint above tells the rewriter that just before it begins to work on
 @('Subgoal *1/3.2''') it should switch to a local theory in which all of the
 rules generated from the event @('nth-nthcdr') are disabled.  That local
 theory remains the one in use for all descendant subgoals generated from the
 one named, until and unless one of those descendant subgoals has an
 @(':in-theory') hint associated with it.  There are many kinds of hints
 besides @(':in-theory') and in general, after each subgoal name, you can give
 various forms of advice and list various adjustments you wish to make to the
 context in which the prover is operating when it begins addressing the subgoal
 named.</p>

 <p>The top-level goal is always named @('Goal').  Thus</p>

 <code>
 (defthm <i>name</i>
         <i>formula</i>
         :hints (("Goal" ...<i>hints1</i>...)
                 ("Subgoal *1/3.2''" ...<i>hints2</i>...)))
 </code>

 <p>has the effect of using <i>hints1</i> for the top-level goal and all of its
 children throughout the entire proof, except for @('Subgoal *1/3.2''') and its
 children, where <i>hints2</i> is used instead.</p>

 <p>There are a few hints which ``take effect'' exactly on the subgoal to which
 they are attached and are not inherited by their descendants.</p>

 <p>Here is an incomplete list of some of the more common hints; we note the
 ones that do not pass on their effects to their descendants.  We recommend
 that you not follow the advanced links (marked ``<see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>'')
 below until you have read the entire tutorial.</p>

 <p>See @(see in-theory) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> for how to enable and/or disable rules.  The new
 theory is computed by a ``theory expression'' (see @(see theories) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>)
 such as @('(disable nth-nthcdr)') and typically makes adjustments such as
 additions or deletions to the global current theory.  All the relevant new
 theories are computed before the proof begins.  Thus, in</p>

 <code>
 (defthm <i>name</i>
         <i>formula</i>
         :hints (("Goal" :in-theory (disable rule1))
                 ("Subgoal *1/3.2''" (disable rule2))))
 </code>

 <p>the theory mentioned for @('Goal') is the global current theory minus
 @('rule1'), while the theory mentioned for its descendant, @('Subgoal
 *1/3.2'''), is the global current theory minus @('rule2').  In particular, if
 both @('rule1') and @('rule2') are enabled in the global current theory, then
 @('rule1') is enabled during the processing of @('Subgoal *1/3.2''') because
 it was not removed explicitly there.</p>

 <p>See @(see use) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> for how to force the theorem prover to
 take note of particular instances of particular theorems; in particular, the
 instances are created and added as hypotheses to the subgoal in question.  The
 hint is not inherited by the descendants of the subgoal (since the formula
 being proved has been modified by the hint).  If the rule you are using (with
 a @(':use') hint) is an enabled rewrite rule, it might interfere with the
 added hypothesis &mdash; by rewriting itself to @('T') &mdash; and thus often
 you will both @(':use ...')  and @(':in-theory (disable ...)').</p>

 <p>See @(see expand) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> for how to tell the theorem prover to expand one or
 more function calls whenever encountered.</p>

 <p>See @(see cases) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> for how to force the theorem prover to do a case
 split to prove the subgoal under each of an exhaustive list of cases given in
 the hint.  This hint takes action specifically at the named subgoal and is not
 passed down to its children.</p>

 <p>See @(see induct) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> for how to tell the theorem prover to go
 immediately into induction for the subgoal in question, and to use the
 induction scheme suggested by the hint rather than the one suggested by the
 terms in the subgoal itself.  This hint is not inherited by its
 descendants.</p>

 <p>See @(see hints) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> for a complete list of all hints, and see @(see
 hints-and-the-waterfall) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> for a more thorough description of how the effects
 of hints at a subgoal are inherited by the descendants.</p>

 <p>If you are reading this as part of the tutorial introduction to the theorem
 prover, use your browser's <b>Back Button</b> now to return to @(see
 introduction-to-the-theorem-prover).</p>")

(defxdoc introduction-to-key-checkpoints
  :parents (introduction-to-the-theorem-prover)
  :short "What questions to ask at key checkpoints"
  :long "<p>We assume you've read about rewrite rules; see @(see
 introduction-to-rewrite-rules-part-1).</p>

 <p>When a proof attempt fails, ACL2 prints some <i>key checkpoints</i>.  These
 are formulas that we think you should look at.  There are two kinds printed:
 key checkpoints <i>before an induction</i>, and key checkpoints <i>under a
 top-level induction</i>.  (Key checkpoints under deeper inductions and
 checkpoints that aren't considered ``key'' may exist in the proof attempt, but
 ACL2 doesn't print them at the end of failed proofs because you shouldn't be
 distracted by them.)</p>

 <p>Below is a list of questions to ask yourself about the key checkpoints.
 Initially, we recommend just picking one key checkpoint <i>before</i> an
 induction (perhaps the simplest looking one) and asking these questions.
 These questions may lead you to look at other key checkpoints.  As you gain
 more experience you'll elaborate and generalize this advice.</p>

 <p><b>(1) Do you believe this formula is a theorem?</b> If you don't think it
 is, it's pointless to try to prove it!  You should reconsider your top-level
 formula in light of the special case suggested by this key checkpoint.</p>

 <p><b>(2) Can it be simplified?</b> Is there some combination of function
 symbols in it that could be eliminated or simplified by exploiting some
 simpler fact?  By a ``simpler fact'' we mean a theorem about a few of the
 symbols in this formula.  For an example of this see @(see
 dealing-with-key-combinations-of-function-symbols).  Don't think about the
 deep question ``how can I prove the checkpoint?'' until you've got it into its
 simplest form.</p>

 <p><b>(3) Is the simpler fact already in the database?</b> If there is some
 simpler fact that would help clean up the checkpoint but you believe the
 simpler fact is already in the database, you can use @(':')@(tsee pl) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>,
 @(':')@(tsee pc) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>, @(':')@(tsee pbt) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>,
 and other <i>history</i> commands to inspect the database; (see @(see history)
 <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>).  But if you find the allegedly relevant simpler
 fact in the database, you must ask: <b>why wasn't it used?</b> There are four
 principal reasons:</p>

 <p>(3a) it is disabled &mdash; so enable it; you'll learn how when you read
 the coming sections on @(see introduction-to-the-database) and @(see
 introduction-to-hints).</p>

 <p>(3b) its left-hand side doesn't match the target &mdash; so improve the
 rule by generalizing its left-hand side or prove a new rule for this
 situation; if you decide to remove the old rule from the database, see
 <i>undo</i> commands in @(see history) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>.</p>

 <p>(3c) it is an @('IFF') rule but the target doesn't occur propositionally
 &mdash; so see if you you can strengthen the rule to an @('EQUAL') rule or
 weaken the context of the target by changing the conjecture to use the target
 propositionally; if you decide to remove the old rule from the database, see
 <i>undo</i> commands in @(see history) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>.</p>

 <p>(3d) the hypotheses of the rule cannot be relieved for this occurrence of
 the target; this can be caused by the rule's hypotheses being too strong
 (requiring more than they should), or by the hypotheses of the current
 conjecture being too weak (you forgot some key hypothesis), or by ACL2 not
 having the rules it needs to prove that the conjecture's hypotheses really do
 imply the rule's.  Tools are available (@(':')see @(see brr) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>)
 help you figure out why the rule failed, so use them and improve the rule, or
 the current conjecture, or the database as appropriate.</p>

 <p><b>(4) If the simpler fact is not already known, prove it.</b> This means
 you must create a new @('defthm') event with appropriate <i>rule-classes</i>
 to store your new theorem so that it will be used.  See @(see
 dealing-with-key-combinations-of-function-symbols).  Then you must start using
 The Method recursively to prove your new lemma.</p>

 <p><b>(5) Otherwise, is this formula something you'd prove by induction?</b>
 If you can't simplify it, it may be because you ``need this fact to prove this
 fact,'' in which case, induction is the right thing to do.  But first,
 remember that in order for a formulas to be provable by induction, it must be
 very general.  Why must it be general?  Because in an inductive proof, the
 main thing you have to work with is the induction hypothesis, which is an
 instance of the theorem you're proving.  If the theorem is not general enough,
 you won't be able to assume an instance that will help you.  ACL2 may try
 induction even on formulas that are not general enough.  Don't assume that the
 formula is ripe for induction just because ACL2 found an induction to do!
 Before you ``approve'' a formula for induction, ask whether it is perhaps a
 special case of some more general theorem.  See @(see
 generalizing-key-checkpoints) now and then come back here.  If you found a
 generalization, you should probably be proving that formula instead of this
 one.  So formulate the appropriate @('defthm') and use The Method recursively
 to prove it.</p>

 <p><b>(6) If the formula is right for induction, did ACL2 do an induction for
 it?</b> You can answer that without looking at the proof.  Just see if there
 are any key checkpoints after induction.  If not, why didn't ACL2 induct?
 Perhaps you told ACL2 not to induct!  Perhaps no term in the conjecture
 suggests an appropriate induction?  You could remedy this by extending ACL2's
 induction analysis by adding to the database.  Or you could just tell ACL2
 what induction to do for this formula.  You'll learn about both later (when
 you read coming sections of the tutorial).</p>

 <p><b>(7) If ACL2 did do an induction, was it the right one?</b> You can find
 the induction scheme used by reading the first induction message in the output
 log after you submitted the conjecture to ACL2.  But most often you will
 realize the ``wrong'' induction was done just by looking at the post-induction
 key checkpoints, keeping in mind that each is supposed to be a natural special
 case of the theorem you're proving.  Is the case analysis inappropriate?  Are
 induction hypotheses missing?  If so, you should look at the induction scheme.
 If you determine the wrong induction was done, extend ACL2's induction
 analysis or tell it which induction to do, which you'll learn about in the
 coming sections of the tutorial.  For more advice about looking at
 post-induction key checkpoints, see @(see post-induction-key-checkpoints) now
 and then come back here.</p>

 <p><b>(8) If the post-induction key checkpoints seems plausible,</b> <b>then
 repeat the questions above for each one of them,</b> <b>perhaps starting with
 the simplest.</b></p>

 <p>In any case, after successfully taking whatever action you've decided on,
 e.g., proving some new lemma and adding it as a rule:</p>

 <p><b>Start over trying to prove your main conjecture.</b> This is important!
 Do not just scroll back to the key checkpoints generated the last time you
 tried to prove it.  Instead, re-generate them in the context of your new,
 improved database and hints.</p>

 <p>You will be following this general outline almost all of the time that
 you're interacting with ACL2.  You will not often be asking ``Why is ACL2
 making me think about this subgoal?  What did ACL2 do to get here?  How does
 ACL2 work?''</p>

 <p>Two other ideas are helpful to keep in mind.</p>

 <p><b>Is a key checkpoint unexpectedly complicated?</b> Pay special attention
 to the case where the complication seems to be the introduction of low-level
 details you thought you'd dealt with or by the introduction of symbols you
 didn't expect to see in this proof.  These can be signs that you ought to
 disable some rules in the database (e.g., a definition of a complicated
 function about which you've proved all the necessary lemmas or some lemma that
 transforms the problem as was appropriate for some other proof).</p>

 <p><b>Does the theorem prover just hang up, printing nothing?</b> If this
 happens, you must interrupt it.  How you interrupt the prover is dependent on
 which Common Lisp and which interface you're using.  But most Common Lisps
 treat control-c as a console interrupt.  If you're in Emacs running ACL2 as a
 shell process, you must type control-c control-c.  If you're in ACL2s, hit the
 <i>Interrupt Session</i> button.  Interrupting ACL2 can leave you in an
 interactive loop similar in appearance but different from ACL2's top-level!
 So pay careful attention to the prompt and see @(see breaks) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>.</p>

 <p>Once you've regained control from the ``runaway'' theorem prover, there are
 several tools you can use to find out what it is doing in real-time.
 Generally speaking, when the theorem prover goes silent for a very long time
 it is either in some kind of rewrite loop caused by rules that cause it to
 flip back and forth between various supposedly normal forms, or else it has
 split the problem into a huge number of cases and suffering a combinatoric
 explosion.  See @(see DMR) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>
 and, perhaps, see @(see accumulated-persistence) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>.</p>

 <p>If you are reading this as part of the tutorial introduction to the theorem
 prover, use your browser's <b>Back Button</b> now to return to @(see
 introduction-to-the-theorem-prover).</p>")

(defxdoc introduction-to-programming-in-acl2-for-those-who-know-lisp
  :parents (programming introduction-to-the-theorem-prover)
  :short "Introduction to programming in ACL2 for Lisp users"
  :long "<p>The @(see documentation) topic, @(see acl2-built-ins), as well as
 its parent topic, @(see programming), are starting points for a rich
 collection of primitives and features in the ACL2 programming language.  In
 the present topic (below) we give a succinct introduction to that language for
 those who are already reasonably familiar with Common Lisp, or perhaps another
 Lisp.  Follow the hyperlinks if you want to drill down; for example, we
 mention multiple values below but say very little about them, instead
 providing links to topics that explain their handling in a little more
 depth.</p>

 <p>The @(tsee documentation) for ACL2 and its @(see community-books) provides
 a rich set of topics for further exploration.  This particular topic is
 intended to serve only as a brief introduction to programming in ACL2 for
 those who know Lisp, especially Common Lisp.  Supplementary reading that may
 interest a few readers includes ``<a
 href='http://www.cs.utexas.edu/users/moore/publications/km97a.pdf'>A Precise
 Description of the ACL2 Logic</a>'' (Matt Kaufmann and J Moore, April,
 1998).</p>

 <h3>Applicative Common Lisp</h3>

 <p>The ACL2 (``A Computational Logic for Applicative Common Lisp'')
 programming language is essentially a subset of Common Lisp &mdash; albeit
 with some useful extensions &mdash; that is <i>applicative</i>: the value
 returned by a function depends only on its inputs, not state.  (There is an
 ACL2 notion of @(see state), introduced briefly below; but that state must be
 passed as an explicit argument.)  Many commonly-used functions and special
 forms in the applicative subset of Common Lisp are also in ACL2, such as (to
 name just a very few) @(tsee car), @(tsee cons), @(tsee nth), @(tsee append),
 @(tsee let), and @(tsee let*).  A few others are not directly included in ACL2
 because they have incomplete specifications in Common Lisp, such as @(tsee
 pairlis); according to the Common Lisp HyperSpec: ``The new pairs may appear
 in the resulting association list in either forward or backward order.''  Many
 such functions tend to have close analogues in ACL2, named by concatenating
 @('"$"') to the Common Lisp name; for example, ACL2 has @(tsee pairlis$),
 @(tsee union$), and even @(tsee random$).  Yet other Common Lisp functions,
 for example @('format'), are not available in ACL2 but have useful
 alternatives in ACL2; for example, see @(tsee fmt).  See @(see acl2-built-ins)
 for a much more comprehensive list of functions, macros, and special forms
 provided by the ACL2 programming language.  In particular, a search through
 that documentation topic for `@('$')' will show you utilities like
 @('pairlis$') that are based on related Common Lisp utilities.</p>

 <p>In the ACL2 read-eval-print loop, you can define functions and macros with
 @(tsee defun) and @(tsee defmacro) just as in Common Lisp, with some
 restrictions (see for example @(see name)) and also some additional @(tsee
 declare) forms.</p>

 <h3>Data types</h3>

 <p>Only certain Lisp data types are supported for programming in ACL2: numbers
 that are either rational numbers or complex numbers with rational
 coefficients (see @(see numbers-introduction)); the @(see characters)
 constructed with @('(code-char n)') for @('n') from 0 to 255; @(see strings)
 formed from those characters; @(see symbols) whose @(tsee symbol-name) and
 @(tsee symbol-package-name) are ACL2 strings; and objects constructed from
 others using @(tsee cons).</p>

 <p>In particular, arrays are not directly supported as an ACL2
 datatype (except for strings).  However, ACL2 supports an applicative notion
 of array, which is logically an association list but has an associated Lisp
 array that provides fast reads in single-threaded programs.  See @(see
 arrays).  If your code creates an array and does many more reads to it than
 writes, or even if there are rarely two writes to the same index (as when
 writes are primarily to initialize the array), then ACL2 arrays may perform
 well.  Otherwise you may get significantly better performance, avoiding the
 consing done by writes (to build the association list), by using a different
 sort of representation of arrays in ACL2: <i>single-threaded objects</i>, or
 <i>stobjs</i>; see @(see stobj).</p>

 <p>Structures can be simulated in ACL2 using suitable macros.  For a simple
 such macro that is built into ACL2, together with alternatives to it, see
 @(see defrec).</p>

 <h3>Program and logic modes</h3>

 <p>If you are using ACL2 as a programming language but you do not intend to
 prove anything about your code, at least not at first, then you might be
 well-served by using @(see program) mode.  In this mode, ACL2 will admit the
 definition if syntactic checks succeed, in particular without requiring a
 proof of termination for recursive definitions.  You can specify the mode
 directly in a declaration (see @(see xargs) for how to specify @(':program')
 in a @(see declare) form), or you can set the default @(see defun-mode) to
 @(':program') (see @(see default-defun-mode) and see @(see program)).</p>

 <p>When you are ready to reason about your functions, you can use @(':')@(tsee
 logic) mode instead, or you can convert a program-mode function to logic-mode
 with @(tsee verify-termination).</p>

 <h3>Connection to Common Lisp</h3>

 <p>Many Common Lisp functions should only be applied to certain types of
 objects: for example, @(tsee car) should only be applied to a cons pair or
 @('nil').  Every ACL2 function has a <i>guard</i>, which specifies the
 intended domain of the function; see @(see guard).  For example, the guard for
 @('car') is @('(OR (CONSP X) (EQUAL X NIL))').  See @(see args) for a utility
 that provides this and other information about a given function symbol.</p>

 <p>Beginning ACL2 programmers should probably ignore guards, at least
 initially.  Otherwise, see @(see xargs) for how to specify a guard; also see
 @(see verify-guards).</p>

 <h3>Multiple values</h3>

 <p>The analogues of Common Lisp utilities @('multiple-value-bind') and
 @('values') are @(tsee mv-let) and @(tsee mv), respectively.  Also see @(see
 b*) for an alternative to @(tsee let*) that can be convenient in the presence
 of multiple values.</p>

 <h3>State</h3>

 <p>ACL2 provides a notion of <i>state</i> that is useful for certain kinds of
 programming.  As mentioned above, the state must be passed explicitly because
 of the applicative nature of ACL2; indeed, it must be passed as the variable,
 @('state'), i.e., the symbol in the @('"ACL2"') package whose @(tsee
 symbol-name) is @('"STATE"').  This is a rather complex notion, perhaps best
 avoided by beginning ACL2 programmers.  To learn about the ACL2 state, see
 @(see state), which points to a topic, @(see programming-with-state), that
 discusses many utilities for reading and writing the ACL2 state.</p>

 <h3>More help</h3>

 <p>ACL2 does not provide @('apropos').  However, you can search the
 documentation to find substring matches.  For example, if you type @('princ')
 into the ``@('Jump to')'' box in the web-based manual, or if you type the
 command @('i') [for ''index''] into the @(see acl2-doc) Emacs-based
 documentation browser, you will find @(tsee princ$).  The ``@('Jump to')'' box
 in the web-based manual matches on prefixes, but the @('i') command in @(see
 acl2-doc) matches on any substring.</p>

 <p>Another way for Lisp programmers to get answers to ``How do I do this in
 ACL2'' questions is to query the acl2-help mailing list.  You can sign up via
 a link on the <a href='http://www.cs.utexas.edu/users/moore/acl2/'>ACL2 home
 page</a>.  Moreover, that could be a good place to request or suggest
 improvements to this documentation topic!  Also see @(see history) for some
 ways to query the current session.</p>

 <p>Finally, here are a few specific alternatives to Common Lisp utilities.</p>

 <ul>

 <li>@('describe'): see @(tsee doc)</li>

 <li>@('fboundp') and other utilities to provide information about functions,
 macros, and special operators: see @(tsee args)</li>

 <li>@('format'): see @(tsee fmt), which has links to related functions that
 perform formatted printing</li>

 <li>@('list-all-packages'): see @(tsee in-package); also see the description
 of @('known-package-alist') in @(see system-utilities)</li>

 <li>@('setq'): see @(tsee assign), but perhaps first look at the documentation
 topics for @(see state) and @(see programming-with-state)</li>

 <li>@('symbol-plist'): see @(tsee props), @(tsee getprop), and @(tsee
 putprop)</li>

 <li>@('with-open-file'): see @(see io)</li>

 </ul>")

(defxdoc introduction-to-rewrite-rules-part-1
  :parents (introduction-to-the-theorem-prover)
  :short "Introduction to ACL2's notion of rewrite rules"
  :long "<p>This topic is an introduction to rewrite rules in ACL2 and is
 intended for the newcomer to ACL2.  The slightly more experienced user might
 benefit from reading @(see random-remarks-on-rewriting) instead.</p>

 <p>Rewrite rules make ACL2 replace one term by another.  This is done
 by the rewriter, which is part of ACL2's simplifier.  The rewriter sweeps
 through the goal formula trying all the @(see rewrite), @(see definition), and
 @(see meta) rules it knows, in order from the most recently submitted rule to
 the oldest, until it finds one to apply.</p>

 <p>Here's an example.  Just pretend that you have made a rewrite rule from the
 formula below.</p>

 @({
  (implies (and (natp i)
                (< i (len a)))
           (equal (put i v (append a b))
                  (append (put i v a) b)))
 })

 <p>Then every time the rewriter sees a target term that <i>matches</i></p>

 @({
  (put i v (append a b))
 })

 <p>it considers the rule, with the variables @('i'), @('v'), @('a'), and
 @('b') of the rule <i>bound</i> to whatever terms matched them in the target,
 say the terms <i>i</i>, <i>v</i>, <i>a</i>, and <i>b</i>.  To consider the
 rule, the rewriter first tries to establish (``relieve'') the hypotheses.  In
 particular, it rewrites:</p>

 <code>
 (natp <i>i</i>)           ; <i>hyp 1</i>
 </code>

 <p>and</p>

 <code>
 (&lt; <i>i</i> (len <i>a</i>)). ; <i>hyp 2</i>
 </code>

 <p>If both hypotheses rewrite to true, then the rule <i>fires</i> and replaces
 the target by:</p>

 <code>
 (append (put <i>i</i> <i>v</i> <i>a</i>) <i>b</i>).
 </code>

 <p>In short, rewrite rules direct ACL2 to rearrange the terms in the goal
 formulas.</p>

 <p>We are more precise later, but for now we turn to the question of how do
 you make a rewrite rule from a formula?  The answer is, you prove the formula
 with the @('defthm') command.  Recall that</p>

 <code>
 (defthm <i>name</i>
         <i>formula</i>
         ...)
 </code>

 <p>commands ACL2 to try to prove <i>formula</i> and, if successful, build it
 into the database as a rule according to your specification in the
 <i>rule-classes</i> argument of the ... part of the command.</p>

 <p>To make it easy for you to generate rewrite rules, @('defthm') has a simple
 heuristic: if you don't tell it what kind of rule to generate from
 <i>formula</i>, it generates a rewrite rule!  Thus, if this command</p>

 <code>
 (defthm <i>name</i>
         <i>formula</i>)
 </code>

 <p>is successful, ACL2 will have a new rewrite rule in the database, even
 though you did not <i>explicitly</i> tell it to add a rule.</p>

 <p>A common mistake for new users is to forget that the above command adds a
 rewrite rule.  This often results in a tangle of rules that lead nowhere or to
 infinite rewriting that you will have to interrupt.  It is also good to
 remember that the command <i>only</i> adds a rule.  It does not magically make
 ACL2 aware of all the mathematical consequences of the formula: it just makes
 a rewrite rule.</p>

 <p>When you prove a theorem with @('defthm') you are <i>programming</i> ACL2.
 Being careless in your statement of lemmas is tantamount to being careless in
 your programming.</p>

 <p>ACL2 can generate rewrite rules from formulas that look like this:</p>

 <code>
 (IMPLIES (AND <i>hyp1</i> ... <i>hypk</i>)
          (<i>eqv</i> <i>lhs</i> <i>rhs</i>))
 </code>

 <p>where <i>eqv</i> is either @('EQUAL') or @('IFF'), and <i>lhs</i> is not a
 variable symbol, not a constant, and not a call of the function @('IF'), and
 not a call of an abbreviation (``macro'') that expands to any of these.  So
 illegal <i>lhs</i> include @('X'), @('0'), @('(IF X Y Y)'), and @('(OR p q)').
 The last is illegal because @('OR') is just an abbreviation for a certain
 @('IF')-expression.</p>

 <p>Technical Note: This tutorial introduction to the theorem prover takes
 liberties with the truth!  We are trying to give you a useful predictive model
 of the system without burdening you with all the details, which are discussed
 in the ACL2 User's Manual.  For example, using directives in the rule-classes
 you can rearrange the proved formula into the form you want your rule to take,
 and you can make ACL2 take advantage of equivalence relations <i>eqv</i> other
 than just @('EQUAL') and @('IFF').  But we'll ignore these fine points for
 now.</p>

 <p>We call the <i>hyp</i> terms the <i>hypotheses</i> of the rule.  We call
 <i>lhs</i> the <i>left-hand side</i> of the rule, and we call <i>rhs</i> the
 <i>right-hand side</i> of the rule.  If the conclusion of the rule is an
 @('EQUAL') term we call it an <i>equality</i> rule.  Otherwise, it is a
 <i>propositional equivalence</i> rule.  If there are no hypotheses,
 <i>k</i>=0, we say the rule is an <i>unconditional</i> rewrite rule; otherwise
 it is <i>conditional</i>.</p>

 <p>ACL2 allows several special cases of the shapes above.  See @(see
 special-cases-for-rewrite-rules), but come back here and continue.</p>

 <p>A rewrite rule makes ACL2 seek out occurrences of terms that match the
 left-hand side of the rule and replace those occurrences using the right-hand
 side, provided all the hypotheses rewrite to true in the context of the
 application of the rule.</p>

 <p>That is, the left-hand side is treated as a <i>pattern</i> that triggers
 the rule.  The hypotheses are <i>conditions</i> that have to be proved in
 order for the rule to fire.  The right-hand side is the <i>replacement</i> and
 is put into the formula where the pattern occurred.</p>

 <p>Now for some clarifications. ACL2 only considers enabled rules.  And ACL2
 will use a propositional rule to replace a target only if the target occurs in
 a propositional place in the formula.  Generally that means it occurs in the
 argument of a propositional connective, like @('AND'), @('OR'), @('NOT'),
 @('IMPLIES'), and @('IFF'), or in the test of an @('IF').  When we say that
 the left-hand side of the rule must <i>match</i> the target we mean that we
 can instantiate the variables in the rule to make the left-hand side identical
 to the target.  To <i>relieve</i> or establish the hypotheses of the rule,
 ACL2 just applies other rewrite rules to try to prove the instantiated
 hypotheses from the assumptions governing the occurrence of the target.  When
 ACL2 replaces the target, it replaces it with the instantiated right-hand side
 of the rule and then applies rewrite rules to that.</p>

 <p>If a hypothesis has variables that do not occur in the left-hand side of
 the rule, then the pattern matching process won't find values for those
 variables.  We call those <i>free variables</i>.  They must be instantiated
 before ACL2 can relieve that hypothesis.  To instantiate them, ACL2 has to
 guess values that would make the hypothesis true in this context, i.e., true
 given the assumptions of the goal theorem.  So if you're trying to prove</p>

 @({
  (IMPLIES (AND (TRUE-LISTP A)
                (MEMBER (CAR P) A)
                (MEMBER (CDR P) A))
           ...)
 })

 <p>and the target you're rewriting is in the ``...'' part of the formula, the
 rewriter knows that @('(TRUE-LISTP A)') @('(MEMBER (CAR P) A)') and @('(MEMBER
 (CDR P) A)') are true.  So if a rewrite rule is considered and the rule has
 @('(member e x)') as a hypothesis, where @('e') is a free variable but @('x')
 was bound to @('A') in the pattern matching, then it will guess that @('e')
 must be @('(CAR P)') or @('(CDR P)'), even though there are many other
 possibilities that would make @('(MEMBER e A)') true.  Of course, whatever
 guess it makes must also satisfy all the other hypotheses that mention @('e')
 in the rule.  It simply isn't very imaginative at guessing!</p>

 <p>The most predictable rewrite rules have no free variables.  You can add
 pragmatic advice to help ACL2 with free variables, telling it to try all the
 possibilities it finds, to try just the first, or even to compute a
 ``creative'' guess.</p>

 <p>It is possible to make the rewriting process loop forever, e.g., by
 rewriting <i>alpha</i> to <i>beta</i> with one set of rules and rewriting
 <i>beta</i> to <i>alpha</i> with another.  Even a single rule can make the
 process loop; we'll show you an example of that later in the tutorial.  ACL2
 can handle commutativity rules without looping.  It uses @('(equal (+ x y) (+
 y x))') to replace @('(+ B A)') by @('(+ A B)'), but not vice versa.  (It is
 sensitive to alphabetic ordering when dealing with <i>permutative</i>
 rules.)</p>

 <p>Logically equivalent formulas can generate radically different rewrite
 rules!  Rearranging the propositional structure of the formula or swapping the
 left and right sides of an equality &mdash; while having no effect on the
 mathematical meaning of a formula &mdash; can have a drastic impact on the
 pragmatic meaning as a rule.  To see an illustration of this, see @(see
 equivalent-formulas-different-rewrite-rules).</p>

 <p>Developing an effective set of rewrite rules is key to success at using
 ACL2.  We'll look more at this later in the tutorial.</p>

 <p>If you are working your way through the tutorial for the theorem prover,
 use your browser's <b>Back Button</b> now to return to @(see
 introduction-to-the-theorem-prover).  If you are reading just about how to
 make effective rewrite rules, go on to @(see
 introduction-to-rewrite-rules-part-2).</p>")

(defxdoc introduction-to-rewrite-rules-part-2
  :parents (introduction-to-the-theorem-prover)
  :short "How to arrange rewrite rules"
  :long "<p>You should design your rewrite rules to canonicalize the terms in
 your problem, that is, your rules should drive terms into some normal form so
 that different but equivalent terms are rewritten into the preferred shape,
 making equivalent terms identical.  You are very familiar with this idea from
 algebra, where you learned to normalize polynomials.  Thus, when you see
 <i>(2x + 6)(3x - 9)</i> you automatically normalize it, by ``multiplying out
 and collecting like terms,'' to get <i>(6x^2 - 54)</i>.  This normalization
 strategy allows you to recognize equivalent terms presented differently, such
 as <i>6(x^2 - 9)</i>.</p>

 <p>The ACL2 user is responsible for making up the rules.  (Standard ``books''
 &mdash; files of ACL2 definitions and theorems &mdash; can often provide rules
 for some sets of functions, e.g., arithmetic.)  This is a heavy burden on you
 but it means you are in charge of your own normal forms.  For example, if you
 use the function @('nthcdr'), which returns the @('n')th @('cdr') of a list,
 you might see both @('(cdr (nthcdr i x))') and @('(nthcdr i (cdr x))').  These
 two expressions are equivalent but not identical.  You will want to decide
 which you want to see and prove the rewrite rule that converts the other to
 that preferred form.</p>

 <p>Most good users develop an implicit ordering on terms and rewrite ``heavy''
 terms to ``lighter'' ones.  This ensures that there are no loops in their
 rewrite rules.  But this ordering changes according to the user and the
 problem.</p>

 <p>Generally, the lightest terms are primitives such as @('IF'), @('EQUAL'),
 arithmetic, etc.  Functions defined without explicit recursion tend to be
 ignored because they are just expanded away (but see below).  Recursively
 defined functions tend to be heavier than any other recursive function used in
 their definitions, so, for example, if @('rev') is defined in terms of
 @('append'), @('rev') is heavier than @('append').  But the size and subtlety
 of recursively defined functions also affects their place in the ordering.</p>

 <p>But rewrite rules are surprisingly subtle.  Recall that a rewrite rule can
 be made from a formula of this form:</p>

 <code>
 (IMPLIES (AND <i>hyp1</i> ... <i>hypk</i>)
          (<i>eqv</i> <i>lhs</i> <i>rhs</i>))
 </code>

 <p>where <i>eqv</i> is either @('EQUAL') or @('IFF'), and <i>lhs</i> is a call
 of a function other than @('IF').  In such a rule, <i>lhs</i> is the pattern
 responsible for triggering the rule, the <i>hypi</i> are conditions which must
 be satisfied by the context of the target being rewritten, and <i>rhs</i> is
 the replacement.  The replacement only happens if the rule is enabled, the
 pattern matches, the conditions are satisfied, and (in the case of an @('IFF')
 rule) the target occurs propositionally.  There are other heuristic
 restrictions that we won't discuss here.</p>

 <p>So how should you phrase a theorem in order to make it an effective
 rule?</p>

 <p>General Principles:</p>

 <p>* <b>Strengthen the Formula</b>: The fewer hypotheses a formula has the
 better the rewrite rule formed from it.  The more general the left-hand side
 the better the rule.  The fewer free variables in the hypothesis, the better.
 The idea is to form a rule that fires predictably.  Later in this tutorial
 you'll get some practice formulating strong rules.</p>

 <p>* <b>Choosing the Conclusion</b>: If a lemma is an implication, you have to
 choose what the conclusion will be. (You'll also have to ``orient'' that
 conclusion by choosing a left-hand side and a right-hand side, but we discuss
 that below).  You can swap the conclusion and any hypothesis by negating both,
 producing a different conclusion.  There are generally two (possibly
 conflicting) heuristics for deciding which part of the formula should be the
 conclusion:</p>

 <p><i>Choosing the Conclusion Heuristic 1</i>: Can you make the conclusion be
 an @('EQUAL') or @('IFF') expression that has a ``heavy term'' on one side?
 That will make a rule that replaces the heavy term with a lighter one.  We
 discuss this situation more below.</p>

 <p><i>Choosing the Conclusion Heuristic 2</i>: Can you make the conclusion be
 a non-propositional term that contains all the variables mentioned in the
 hypotheses?  By ``non-propositional'' we mean a term that is not just the
 propositional combination (e.g., with @('AND') or @('OR')) of other terms but
 instead some call of some ``heavy'' function?  If your conclusion contains all
 the variables mentioned in the hypotheses, matching it will instantiate all
 the variables in the hypotheses.  That way ACL2 will not have to guess
 instantiations of unbound variables when it tries to relieve the hypotheses.
 It is not very good at guessing.</p>

 <p>* <b>Orienting the Conclusion</b>: If the conclusion is an @('EQUAL') or an
 @('IFF'), you have to decide which is the left-hand side and which is the
 right.  If the conclusion is @('(NOT') <i>lhs</i>@(')'), then the left-hand
 side is <i>lhs</i> and the right-hand side is @('NIL').  If the conclusion is
 not an @('EQUAL'), an @('IFF'), or a @('NOT') then the conclusion itself will
 be the left-hand side and the right-hand side will be @('T').  If your lemma
 was created by looking at Key Checkpoints while using The Method, the
 left-hand side should match some term in that checkpoint.</p>

 <p>Remember, the left-hand side is the ``trigger'' that will make the rule
 fire.  It is the pattern that ACL2 will be looking for.</p>

 <p>* <b>Pay attention to the free variables</b>: Look at the variables that
 occur in the pattern (the left-hand side) and compare them to the variables
 that occur in the hypotheses.  Does some hypothesis contain a variable, say
 <i>v</i>, that is not in the pattern?  We call <i>v</i> a <i>free variable</i>
 because it will not be assigned a value (``bound'') by the process of pattern
 matching.  ACL2 will have to guess a value for <i>v</i>.  If some hypothesis
 contains <i>v</i> as a free variable, ask whether more than one hypothesis
 contains <i>v</i>?  ACL2 uses the first hypothesis containing a free <i>v</i>
 to guide its guess for <i>v</i>.  To ``guess'' a value for <i>v</i>, ACL2 uses
 that hypothesis as a pattern and tries to match it against the assumptions in
 the checkpoint formula being proved.  This means that key hypotheses must be
 in normal form, to match the rewritten assumptions of the goal.  It also means
 that you should reorder the hypotheses to put the most unusual hypothesis
 containing a free <i>v</i> first in the list of conjuncts.  For example, if
 @('v') is free in two hypotheses, @('(natp v)') and @('(member (nthcdr v a)
 b)'), then we recommend putting the @('member') term first.  There are likely
 to be many terms in the goal satisfying the @('natp') hypothesis &mdash; or
 none if @('natp') has expanded to an integer inequality &mdash; while there
 are likely to be few terms satisfying the @('member') hypothesis, especially
 if @('a') and @('b') are bound by the left-hand side of the rule.</p>

 <p>Here are some (possibly conflicting) heuristics for choosing the left-hand
 side:</p>

 <p><i>Choose a Left-Hand Side that Occurs in a Key Checkpoint</i>: If you use
 the Method you will tend to do this anyway, because you'll see terms in the
 Key Checkpoints that you want to get rid of.  But many moderately experienced
 users ``look ahead'' to how the proof will go and formulate a few anticipatory
 rules with the idea of guiding ACL2 down the preferred path to the proof.
 When you do that, you risk choosing left-hand sides that won't actually arise
 in the problem.  So when you formulate anticipatory rules, pay special
 attention to the functions and terms you put in the left-hand sides.  The next
 few paragraphs deal with specific cases.</p>

 <p><i>Avoid Non-Recursive Functions in the Left-Hand Side</i>: If the
 left-hand side contains a call of a defined function whose definition is not
 recursive, then it will almost never match any target in the formula being
 rewritten unless the function is disabled.  Suppose for example you have
 defined @('SQ') so that @('(SQ x)') is @('(* x x)').  Suppose you considered
 choosing a left-hand side like @('(+ (SQ x) (SQ y))').  Suppose you hoped it
 would hit the target @('(+ (SQ A) (SQ B))') in some formula.  But when ACL2
 simplifies the formula, it will first rewrite that target to</p>

 @({
  (+ (* A A) (* B B))
 })

 <p>by expanding the definition of @('SQ'), since it could do so without
 introducing any recursive calls.  But now the target won't match your rule.
 By choosing a left-hand side that occurs in a Key Checkpoint (and is not one
 of a handful of abbreviations ACL2 uses in its output like @('AND'),
 @('NOT')), you'll avoid this problem since @('SQ') will have already been
 expanded before the Key Checkpoint is printed.</p>

 <p><i>Disable Non-Recursive Functions</i>: If you insist on a left-hand side
 that contains calls of non-recursive functions, remember to disable those
 non-recursive functions after you've proved all the rules you want about them.
 By disabling @('SQ') you can prevent ACL2 from expanding the definition as it
 did above.  Sometimes you will define a function non-recursively to formalize
 some concept that is common in your application and you will want to create a
 sort of algebra of rules about the function.  By all means do so, so you can
 conduct your formal reasoning in terms of the concepts you're informally
 manipulating.  But after proving the required laws, disable the non-recursive
 concept so that ACL2 just uses your laws and not the messy definition.</p>

 <p><i>Choose a Left-Hand Side Already in Simplest Form</i>: This is a
 generalization of the advice above.  If any rule will rewrite your left-hand
 side, it will prevent your rule from matching any target.  For example, if you
 write a left-hand side like @('(foo (car (cons x y)))') then it would never
 match any target!  The reason is that even if @('(FOO (CAR (CONS A B)))') did
 occur in some goal formula, before ACL2 would try your rule about @('foo') it
 will use the obvious rule about @('CAR') and @('CONS') to transform your
 imagined target to @('(FOO A)').  Thus, your rule would not match.  So you
 have to keep in mind <i>all your other rules</i> when you choose a left-hand
 side (and when you choose the hypotheses to guide free variable selection).
 If you always choose a pattern that matches a term in a Key Checkpoint, you
 avoid this problem.  Also see @(see community-books) example
 @('books/demos/knuth-bendix-problem-1.lisp').</p>

 <p><i>Make Sure the Left-Hand Side is ``Heavier'' than the Right</i>:
 Sometimes this is obvious, as when you choose @('(REV (REV x))') for the
 left-hand side and @('x') for the right.  But what do you about @('(REV
 (APPEND x y))') versus @('(APPEND (REV y) (REV x))')?  Most of the time we
 choose to drive the heaviest function (in this case @('REV')) down toward the
 variables, lifting the lighter function (@('APPEND')) up so that we can reason
 about the lighter function's interaction with the surrounding ``matrix'' of
 the formula.  So we'd rewrite @('(REV (APPEND x y))') to @('(APPEND (REV y)
 (REV x))'), not vice versa.</p>

 <p><i>Alternative Ways to Talk About the Same Thing</i>: If your problem and
 specification use two different ways to talk about the same thing, choose one
 form and rewrite the other into that form.  For example, the ACL2 built-in
 @('nth') returns the nth element of a list, and the built-in function
 @('nthcdr') returns the nth @('cdr') of a list.  They are defined
 independently.  But @('(nth n x)') is the same thing as @('(car (nthcdr n
 x))').  Since @('nth') can be expressed in terms of @('nthcdr') but not vice
 versa, it is clear we should prove @('(equal (nth n x) (car (nthcdr n x)))')
 as a rewrite rule if both @('nth') and @('nthcdr') are involved in the
 problem.</p>

 <p><i>Don't Let Computational Efficiency Dictate the Terms</i>: If you have
 two functions that are equivalent (perhaps one was defined to be
 computationally more efficient), prove their equivalence as a rewrite rule
 that eliminates the more complicated function.  An extreme example would be a
 model that uses a sophisticated data structure (like a balanced binary tree,
 red-black tree, ordered array, or hash table) to implement something simple
 like an association of keys to values.  By proving the equivalence as stated
 you can eliminate the messy function early and do the bulk of your reasoning
 in terms of its simple specification.</p>

 <p>The best ACL2 users become very good at keeping all these things in mind
 when designing their rewrite rules.  Practice makes perfect.  Don't be afraid
 during your learning of ACL2 to undo the rules you first invented and try to
 make better ones.</p>

 <p>Finally, be patient!  There will be times when you think to yourself ``Why
 should I spend my time thinking of rules that guide ACL2?  I know the proof!''
 There are two reasons.  First, you may ``know'' the proof but you may well be
 wrong and part-way through this whole exercise you may realize that you're
 missing a major hypothesis or special case that breaks your whole conception
 of the problem.  The proof is in the details.  Second, most of the time the
 library of rules you develop in this process will be used over and over again
 on variants of the main problem in the months and years ahead.  This is
 sometimes called the <i>proof maintenance</i> problem.  Theorems don't suffer
 bit rot!  But the artifacts you're modeling change and you will need to prove
 new versions of old theorems.  A good general purpose library makes this much
 easier.</p>

 <p>We now recommend that you practice inventing strong rules; see @(see
 strong-rewrite-rules).</p>

 <p>For advice on handling specific kinds of formulas and definitions, see
 @(see specific-kinds-of-formulas-as-rewrite-rules).</p>

 <p>For more information about the rewriter works and how rules are created,
 see @(see further-information-on-rewriting).</p>

 <p>If you are working your way through the tutorial introduction to the
 theorem prover, use your browser's <b>Back Button</b> to return to @(see
 introduction-to-the-theorem-prover).</p>")

(defxdoc introduction-to-the-database
  :parents (introduction-to-the-theorem-prover)
  :short "How to update the database"
  :long "<p>We assume you've read @(see introduction-to-rewrite-rules-part-1)
 and @(see introduction-to-key-checkpoints).</p>

 <p>The theorem prover's heuristics are influenced by the database of rules and
 the enabled/disabled status of the rules.  You can think of the database as a
 <i>global</i> hint, potentially affecting all parts of a proof attempt.</p>

 <p>However, in addition to the ``global hint,'' it is possible to give
 <i>local</i> hints that affect the theorem prover's behavior on specific
 subgoals.  We discuss the database here and discuss local hints later in the
 tutorial.</p>

 <p>The theorem prover's ``database'' is called the <i>ACL2 world</i>.  You
 change the world by issuing commands called <i>events</i>.  The most common
 events are @('defun') for defining new functions (and predicates) and
 @('defthm') for proving new theorems.  Both add rules to the database.  Here
 are some commonly used events.</p>

 <p>We recommend that upon the first reading of this tutorial you do not follow
 the links shown below!  The links take you into the hypertext reference
 manual, where it is easy to get lost unless you're looking for detail about
 one specific feature.</p>

 <p>See @(see defun) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> to define a new function or predicate symbol.
 Definitional axioms are just a kind of @('rewrite') rule, but @('defun') may
 also add rules affecting the determination of the type of a term and rules
 affecting the induction analysis.  When you issue a @('defun') command you
 will always supply the <i>name</i> of the function or predicate, the list of
 <i>formal parameters</i>, <i>v1,...vn</i>, and the <i>body</i>:</p>

 <code>
 (defun <i>name</i> (<i>v1 ... vn</i>)
    <i>body</i>)
 </code>

 <p>If the event is accepted, a <i>definitional axiom</i> is added to the
 world, @('(')<i>name</i> <i>v1...vn</i>@(')')=<i>body</i>, stored as a special
 kind of unconditional rewrite rule.  However, the @('defun') event may require
 theorems to be proved.  Specifically, <i>measure theorems</i> must be proved
 to establish that recursively defined functions always terminate, by proving
 that an <i>ordinal</i> measure of the formal parameters decreases in a
 <i>well-founded</i> way in every recursive call.  In addition, if
 <i>guards</i> are being used to declare the <i>expected domain</i> of the
 newly defined function, <i>guard theorems</i> might be proved to establish
 that all functions stay within their expected domains.  In any case, you may
 provide additional information to the @('defun') event, coded as part of the
 @('declaration') that Common Lisp allows:</p>

 <code>
 (defun <i>name</i> (<i>v1 ... vn</i>)
    (declare (xargs ...))
    <i>body</i>)
 </code>

 <p>The @('xargs') (``extra arguments to @('defun')'') entry may specify, among
 other things, the measure to use in the termination proof, hints for use by
 the prover during the termination proof, the guard of the new function, and
 hints for use by the prover during the guard verification step.</p>

 <p>See @(see defthm) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> to prove a theorem and to add it as a rule of one
 or more specified rule-classes.  When you issue a @('defthm') command you
 always specify a <i>name</i> for the theorem you're trying to prove and a
 <i>formula</i> stating the theorem.  You may optionally supply some local
 hints as we describe later in the tutorial.  You may also optionally supply
 some <i>rule classes</i> indicating how you want your formula stored as a
 rule, after it is proved.  We discuss the @('defthm') <i>rule classes</i>
 below.</p>

 <p>See @(see in-theory) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> to enable or disable rules.  Rules have names
 derived from the names you give to functions and theorems, e.g., @('(:REWRITE
 LEFT-IDENTITY-OF-FOO . 2)') for the second rewrite rule you created from the
 theorem named @('LEFT-IDENTITY-OF-FOO').  Rule names are called <i>runes</i>.
 A <i>theory</i> is just a set (list) of runes.  The <i>current theory</i> is
 the list of enabled runes and the @('in-theory') event can add runes to or
 delete runes from the current theory.</p>

 <p>See @(see include-book) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> to change the world by loading a
 certified file of other events.  The most common use of @('include-book') is
 to load ``community books'' &mdash; books written by other ACL2 users who have
 released them for distribution to the community.  The most common books loaded
 are probably the arithmetic books:</p>

 <code>
 ; * for the most elementary arithmetic, needed for any problem
 ;   that involves even simple addition and multiplication like
 ; @('(+ x (* 2 y) -3)'):

     (include-book "arithmetic/top-with-meta" :dir :system)

 ; * for more complicated arithmetic involving non-linear terms like
 ; @('(* x y)'), @('(expt x (+ i j))'), and @('floor') and @('mod')

     (include-book "arithmetic-5/top" :dir :system)
 </code>

 <p>But for a complete list of system books, see @(see books) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>.</p>

 <p>See @(see certify-book) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see> to
 certify a file of events for reuse later.</p>

 <p>See @(see defconst) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> to define a new constant, allowing you to write a
 symbol, e.g., @('*weekdays*') in place of some object, e.g., @(''(MON TUE WED
 THU FRI)') in formulas.</p>

 <p>See @(see defmacro) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> to define a new syntactic abbreviation.  The macro
 facility in Lisp is quite powerful, allowing you to <i>compute</i> the form to
 which some type-in expands.  For example, the primitive macro @('COND') is
 defined so that @('(COND ((P X) 1)((Q X) 2)(T 3))') expands to @('(IF (P X)
 1 (IF (Q X) 2 3))').</p>

 <p>See @(see defstobj) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> to introduce a <i>single-threaded object</i> that
 your functions may modify ``destructively'' provided they follow strict
 syntactic rules.</p>

 <p>See @(see events) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> for a complete list of the ACL2 events.  There are
 events to allow mutually recursive definitions, to introduce some new function
 symbols constrained to satisfy given axioms, to allow the temporary
 introduction of a ``local'' event to help prove some goal theorem and then
 disappear, to provide the power of first-order quantification and a choice
 operator, and many other features.</p>

 <p>There are also commands that allow you to inspect the world, e.g., to print
 the command that introduced a given name, to show all the commands back to a
 certain one, undo the last command or more generally roll-back to an earlier
 command.  See @(see history) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>.</p>

 <p><b>The Defthm Rule-Classes</b></p>

 <p>We've already discussed the key role that rules play in controlling the
 behavior of the system.  New rules are introduced primarily with the
 @('defthm') event, though @('defun') and other events may introduce rules.</p>

 <p>To prove <i>formula</i> and generate, say a @(':rewrite') rule and a
 @(':generalize') rule from it, you would write</p>

 <code>
 (defthm <i>name</i>
         <i>formula</i>
         :rule-classes (:rewrite :generalize))
 </code>

 <p>If you wanted to rearrange the shape of the formula before generating the
 @(':rewrite') rule you could provide a @(':corollary') modifier to the
 @(':rewrite') rule class:</p>

 <code>
 (defthm <i>name</i>
         <i>formula</i>
         :rule-classes ((:rewrite :corollary ...)
                        :generalize)).
 </code>

 <p>There are many classes of rules, affecting different parts of the system.
 Each class is denoted by a keyword, e.g., @(':REWRITE'), @(':LINEAR'), etc.
 You are responsible for specifying the class(es) of rules to be generated from
 a given formula and several different rules (possibly of different classes)
 may be derived from a single formula.  Each class admits optional modifiers
 that allow you finer control over each rule.  Each class admits the
 @(':corollary') modifier with which you can rearrange the formula before a
 rule of that class is generated.  This allows you to state a theorem in its
 most elegant form for publication purposes but store it as a rule with the
 most appropriate hypotheses and conclusion.  Other modifiers tend to be
 specific to certain rule classes, but for example, @(':rewrite') rule
 modifiers include an optional limit on the depth of backchaining and options
 for handling free variables.</p>

 <p>We give some links below to other classes of rules.  However, we recommend
 that you not follow these links upon your first reading of this tutorial!</p>

 <p>See @(see REWRITE) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> for a description of how to create a rewrite
 rule.</p>

 <p>See @(see LINEAR) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> for a description of how to store theorems
 concluding with arithmetic inequalities.  The trouble with storing</p>

 @({
  (<= (len (delete e x)) (len x))
 })

 <p>as a rewrite rule is that it only matches instances of that inequality and
 thus fails to match</p>

 @({
  (<= (LEN (DELETE E X)) (+ 1 (LEN X)))
 })

 <p>ACL2 contains an extensible linear arithmetic decision procedure and by
 storing inequalities as @(':linear') rules you can make that decision
 procedure aware of the basic inequalities between non-primitive numerically
 valued terms.</p>

 <p>See @(see EQUIVALENCE) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>, see @(see CONGRUENCE) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>,
 and see @(see REFINEMENT) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> to learn how to introduce a new equivalence
 relation to the rewriter.  For example, suppose you define @('set-equal') so
 that it returns t precisely if its two arguments are lists containing the same
 elements, regardless of order or number of occurrences.  Note that under this
 sense of ``equivalence'', @('(rev x)') is the identity function and
 @('append') is commutative, for example.</p>

 @({
  (set-equal (rev x) x)

  (set-equal (append x y) (append y x))
 })

 <p>You can make ACL2 use these two theorems as @(':rewrite') rules to replace
 instances of @('(REV x)') and @('(APPEND x y)') by @('set-equal') terms, even
 though the results are not actually @('EQUAL').  This is possible provided the
 target occurs in a context admitting @('set-equal') as a congruence relation.
 For example, the congruence rule:</p>

 @({
  (implies (set-equal a b)
           (iff (member e a)
                (member e b)))
 })

 <p>gives the rewriter permission to use the above @('set-equal') rules as
 rewrite rules in the second argument of any @('member') expression being used
 in a propositional way.</p>

 <p>See @(see ELIM) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> for a description of how to make the system adopt a
 ``change of variable'' tactic that can trade in <i>destructor</i> functions
 for <i>constructor</i> functions.  In analogy with how ACL2 eliminates @('(CAR
 X)') and @('(CDR X)') by replacing @('X') with @('(CONS A B)'), you can make
 it eliminate other destructors.  For example, the community book
 @('"arithmetic-5/top"') provides an @('elim') rule that eliminates @('(floor
 x y)') and @('(mod x y)') by replacing @('x') by @('(+ r (* y q))'), so that
 the @('floor') expression becomes @('q') and the @('mod') expression becomes
 @('r').  When introducing your own @('elim') rules you will probably also need
 to introduce @('generalize') rules (see below) so that the new variables are
 appropriately constrained.</p>

 <p>See @(see GENERALIZE) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> for a description of how you can make ACL2 restrict
 the new variables it introduces when generalizing.  ACL2 will sometimes
 replace a term by a new variable and with @('generalize') rules you can ensure
 that the new variable symbol has certain properties of the term it
 replaces.</p>

 <p>See @(see INDUCTION) <see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see> for a description of how to tailor the inductions
 suggested by a term.  Most of the time when ACL2 chooses the ``wrong''
 induction, the easiest fix is with a local @(':induct') hint (see below).  But
 if the same problem arises repeatedly in several theorems, you might want to
 ``educate'' ACL2's induction heuristic.</p>

 <p>For a complete list of rule-classes, See @(see rule-classes) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>.</p>

 <p>If you are reading this as part of the tutorial introduction to the theorem
 prover, use your browser's <b>Back Button</b> now to return to @(see
 introduction-to-the-theorem-prover).</p>")

(defxdoc introduction-to-the-tau-system
  :parents (tau-system)
  :short "A decision procedure for runtime types"
  :long "<p>This doc topic is the main source of information about the tau
 system and discusses the general idea behind the procedure and how to exploit
 it.</p>

 <p><i>A ``Type-Checker'' for an Untyped Language</i></p>

 <p>Because ACL2 is an untyped language it is impossible to type check it.  All
 functions are total.  An <i>n</i>-ary function may be applied to any
 combination of <i>n</i> ACL2 objects.  The syntax of ACL2 stipulates that
 @('(')<i>fn a1...an</i>@(')') is a well-formed term if <i>fn</i> is a function
 symbol of <i>n</i> arguments and the <i>ai</i> are well-formed terms.  No
 mention is made of the ``types'' of terms.  That is what is meant by saying
 ACL2 is an untyped language.</p>

 <p>Nevertheless, the system provides a variety of monadic Boolean function
 symbols, like @(tsee natp), @(tsee integerp), @(tsee alistp), etc., that
 recognize different ``types'' of objects at runtime.  Users typically define
 many more such recognizers for domain-specific ``types.''  Because of the
 prevalence of such ``types,'' ACL2 must frequently reason about the inclusion
 of one ``type'' in another.  It must also reason about the consequences of
 functions being defined so as to produce objects of certain ``types'' when
 given arguments of certain other ``types.''</p>

 <p>Because the word ``type'' in computer science tends to imply syntactic or
 semantic restrictions on functions, we avoid using that word henceforth.
 Instead, we just reason about monadic Boolean predicates.  You may wish to
 think of ``tau'' as synonymous with ``type'' but without any suggestion of
 syntactic or semantic restrictions.</p>

 <p><i>Design Philosophy</i></p>

 <p>The following basic principles were kept in mind when developing tau
 checker and may help you exploit it.</p>

 <p>(1) The tau system is supposed to be a lightweight, fast, and helpful
 decision procedure for an elementary subset of the logic focused on monadic
 predicates and function signatures.</p>

 <p>(2) Most subgoals produced by the theorem prover are not in any decidable
 subset of the logic!  Thus, decision procedures fail to prove the vast
 majority of the formulas they see and will be net time-sinks if tried too
 often no matter how fast they are.</p>

 <p>Tau reasoning is used by the prover as part of @('preprocess-clause'), one
 of the first proof techniques the system tries.  The tau system filters out
 ``obvious'' subgoals.  The tau system is only tried when a goal first enters
 the waterfall and when a goal is stable under simplification.</p>

 <p>(3) The tau system is ``benign'' in the sense that the only way it
 contributes to a proof is to eliminate (prove!) subgoals.  It does not
 rewrite, simplify, or change formulas.  Tau reasoning is not used by the
 rewriter.  The tau system either eliminates a subgoal by proving it or leaves
 it unchanged.</p>

 <p>(4) It is impossible to infer automatically the relations between arbitrary
 recursively defined predicates and functions.  Thus, the tau system's
 knowledge of tau relationships and function signatures is gleaned from
 theorems stated by the user and proved by the system.</p>

 <p>(5) Users wishing to build effective ``type-checkers'' for their models
 must learn how rules affect the tau system's behavior.  There are two main
 forms of tau rules: those that reveal inclusion/exclusion relations between
 named tau predicates, e.g., that 16-bit naturals are also 32-bit naturals,</p>

 @({
  (implies (n16p x) (n32p x)),
 })

 <p>and signatures for all relevant functions, e.g., writing a 32-bit natural
 to a legal slot in a register file produces a register file:</p>

 @({
  (implies (and (natp n)
                (< n 16)
                (n32p val)
                (register-filep regs))
           (register-filep (update-nth n val regs))).
 })

 <p>For a complete description of acceptable forms see @(':')@(tsee
 tau-system).</p>

 <p>(6) The tau system is ``greedy'' in its efforts to augment its database.
 Its database is potentially augmented when rules of <i>any</i>
 @(':rule-class') (see @(':')@(tsee rule-classes)) are proved.  For example, if
 you make a @(':')@(tsee rewrite) or @(':')@(tsee type-prescription) rule which
 expresses a relationship between one tau and another (e.g., that @('(P x)')
 implies @('(Q x)')), ACL2 will build it into the tau database.  The rule-class
 @(':')@(tsee tau-system) can be used to add a rule to the tau database without
 adding any other kind of rule.</p>

 <p>(7) Greediness is forced into the design by benignity: the tau system may
 ``know'' some fact that the rewriter does not, and because tau reasoning is
 not used in rewriting, that missing fact must be conveyed to the rewriter
 through some other class of rule, e.g., a @(':')@(tsee rewrite) or
 @(':')@(tsee type-prescription) or @(':')@(tsee forward-chaining) rule.  By
 making the tau system greedy, we allow the user to program the rewriter and
 the tau system simultaneously while keeping them separate.  However, this
 means you must keep in mind the effects of a rule on <i>both</i> the rewriter
 and the tau system and use @(':')@(tsee tau-system) rules explicitly when you
 want to ``talk'' just to the tau system.</p>

 <p>(8) Tau rules are built into the database with as much preprocessing as
 possible (e.g., the system transitively closes inclusion/exclusion
 relationships at rule-storage time) so the checker can be fast.</p>

 <p>(9) For speed, tau does not track dependencies and is not sensitive to the
 enabled/disabled status (see @(tsee enable) and @(tsee disable)) of rules,
 other than @(see executable-counterpart) rules.  Once a fact has been built
 into the tau database, the only way to prevent that fact from being used is by
 disabling the entire tau system, by disabling @('(:')@(tsee
 executable-counterpart)@(' tau-system)').  If any tau reasoning is used in a
 proof, the rune @('(:')@(tsee executable-counterpart)@(' tau-system)') is
 reported in the @(see summary).  For a complete list of all the runes in the
 tau database, evaluate @('(get-tau-runes (w state))').  Any of these
 associated theorems could have been used.</p>

 <p>These design criteria are not always achieved!  For example, the tau
 system's ``greediness'' can be turned off (see @(tsee set-tau-auto-mode)), the
 tau database can be regenerated from scratch to ignore disabled rules (see
 @(tsee regenerate-tau-database)), and disabling the @(see
 executable-counterpart) of a tau predicate symbol will prevent the tau system
 from trying to run the predicate on constants.  The tau system's benignity can
 be frustrating since it might ``know'' something the rewriter does not.  More
 problematically, the tau system is not always ``fast'' and not always
 ``benign!''  The typical way tau reasoning can slow a proof down is by
 evaluating expensive tau predicates on constants.  The typical way tau
 reasoning can hurt a previously successful proof is by proving some subgoals
 (!) and thus causing the remaining subgoals to have different @(see
 clause-identifier)s, thus making explicit hints no longer applicable.  We deal
 with such problems in @(tsee dealing-with-tau-problems).</p>

 <p><i>Technical Details</i></p>

 <p>The tau system consists of both a database and an algorithm for using the
 database.  The database contains theorems that match certain schemas allowing
 them to be stored in the tau database.  Roughly speaking the schemas encode
 ``inclusion'' and ``exclusion'' relations, e.g., that @('natp') implies
 @('integerp') and that @('integerp') implies not @('consp'), and they encode
 ``signatures'' of functions, e.g., theorems that relate the output of a
 function to the input, provided only tau predicates are involved.</p>

 <p>By ``tau predicates'' we mean the application of a monadic Boolean-valued
 function symbol, the equality of something to a quoted constant, an arithmetic
 ordering relation between something and a rational constant, or the logical
 negation of such a term.  Here are some examples of tau predicates:</p>

 @({
  (natp i)
  (not (consp x))
  (equal y 'MONDAY)
  (not (eql 23 k))
  (< 8 max)
  (<= max 24)
 })

 <p>Synonyms for @(tsee equal) include @(tsee =), @(tsee eq), and @(tsee eql).
 Note that negated equalities are also allowed.  The arithmetic ordering
 relations that may be used are @(tsee <), @(tsee <=), @(tsee >=), and @(tsee
 >).  One of the arguments to every arithmetic ordering relation must be an
 integer or rational constant for the term to be treated as a tau
 predicate.</p>

 <p>A ``tau'' is a data object representing a set of signed (positive or
 negative) tau predicates whose meaning is the conjunction of the literals in
 the set.</p>

 <p>When we say that a term ``has'' a given tau we mean the term satisfies all
 of the recognizers in that tau.</p>

 <p>The tau algorithm is a decision procedure for the logical theory described
 (only) by the rules in the database.  The algorithm takes a term and a list of
 assumptions mapping subterms (typically variable symbols) to tau, and returns
 the tau of the given term.</p>

 <p>When the system is called upon to decide whether a term satisfies a given
 monadic predicate, it computes the tau of the term and asks whether the
 predicate is in that set.  More generally, to determine if a term satisfies a
 tau, <i>s</i>, we compute a tau, <i>r</i>, for the term and ask whether
 <i>s</i> is a subset of <i>r</i>.  To determine whether a constant, <i>c</i>,
 satisfies tau <i>s</i> we apply each of the literals in <i>s</i> to <i>c</i>.
 Evaluation might, of course, be time-consuming for complex user-defined
 predicates.</p>

 <p>The tau database contains rules derived from definitions and theorems
 stated by the user.  See @(':')@(tsee tau-system) for a description of the
 acceptable forms of tau rules.</p>

 <p>To shut off the greedy augmentation of the tau database, see @(see
 set-tau-auto-mode).  This may be of use to users who wish to tightly control
 the rules in the tau database.  To add a rule to the tau database without
 adding any other kind of rule, use the rule class @(':')@(tsee
 tau-system).</p>

 <p>There are some slight complexities in the design related to how we handle
 events with both @(':tau-system') corollaries and corollaries of other
 @(':rule-classes'), see @(tsee set-tau-auto-mode).</p>

 <p>To prevent tau reasoning from being used, disable the @(':')@(tsee
 executable-counterpart) of @('tau-system'), i.e., execute</p>

 @({
  (in-theory (disable (:executable-counterpart tau-system)))
 })

 <p>or, equivalently,</p>

 @({
  (in-theory (disable (tau-system)))
 })

 <p>To prevent tau from being used in the proof of a particular subgoal,
 locally disable the @(':')@(tsee executable-counterpart) of @('tau-system')
 with a local @(':in-theory') hint (see @(see hints)).</p>

 <p>The event command @(tsee tau-status) is a macro that can be used to toggle
 both whether tau reasoning is globally enabled and whether the tau database is
 augmented greedily.  For example, the event</p>

 @({
  (tau-status :system nil :auto-mode nil)
 })

 <p>prevents the tau system from being used in proofs and prevents the
 augmentation of the tau database by rules other than those explicitly labeled
 @(':')@(tsee tau-system).</p>

 <p>To see what the tau system ``knows'' about a given function symbol see
 @(see tau-data).  To see the entire tau database, see @(see tau-database).  To
 regenerate the tau database using only the runes listed in the current enabled
 theory, see @(see regenerate-tau-database).</p>")

(defxdoc introduction-to-the-theorem-prover
  :parents (acl2-tutorial)
  :short "How the theorem prover works — level 0"
  :long "<p>Software is complex, and ACL2 is a piece of software that is used
 to analyze software &mdash; adding another layer of complexity.  Furthermore,
 instead of being limited to static analysis for certain fixed properties, ACL2
 allows you &mdash; indeed, forces you &mdash; to formalize the problem and the
 questions.  It ``knows'' nothing inherent about your problem before you start
 to interact with it.  But it can be used to help answer the most complicated
 questions you can ask about software.</p>

 <p>All this is to say that it is not the kind of tool that you just install
 and then start to use effectively.  So OK, you've installed it or confirmed
 that you can invoke it.  Good for you.  Now you have to learn how to use it!
 Your success ultimately comes down to your understanding of your problem
 domain and your appropriate exploitation of ACL2's strengths and avoidance of
 its weaknesses.  So put aside the idea of sitting down and interacting with
 it.  Instead, learn about it.</p>

 <p>We assume you know some of the <see topic='@(url
 INTERESTING-APPLICATIONS)'>industrial applications</see> of ACL2.  Realizing
 that such things can be done may sustain you during the long learning curve!
 We also assume you have taken both the <see topic='@(url
 |A Flying Tour of ACL2|)'>Flying Tour</see> and the <see topic='@(url
 |A Walking Tour of ACL2|)'>Walking Tour</see>.  The tours give you a good
 overview of the whole system where this tutorial focuses on how to use the
 prover itself.</p>

 <p>If you haven't visited these links, please do so now.</p>

 <p>This tutorial will take you several hours &mdash; maybe several days
 &mdash; to work through.  Do not breeze through it as you might a blog.
 <i>Think</i> your way through it.  <i>Remember</i> what you read.  Do not take
 short cuts.  If you start to use ACL2 before you really know how, it will only
 frustrate you.</p>

 <p>We recommend that you read this tutorial with an HTML browser so that you
 can see which links you've followed and which you have not.  To give you a
 sense of what is in store, here is a map of this document.  But don't navigate
 through it from here! Read it linearly, following the links when the text
 directs you to.</p>

 <code>
  @(see INTRODUCTION-TO-THE-THEOREM-PROVER)
      @(see INTRODUCTION-TO-REWRITE-RULES-PART-1)
          @(see SPECIAL-CASES-FOR-REWRITE-RULES)
          @(see EQUIVALENT-FORMULAS-DIFFERENT-REWRITE-RULES)
      @(see INTRODUCTION-TO-KEY-CHECKPOINTS)
          @(see DEALING-WITH-KEY-COMBINATIONS-OF-FUNCTION-SYMBOLS)
          @(see GENERALIZING-KEY-CHECKPOINTS)
          @(see POST-INDUCTION-KEY-CHECKPOINTS)
      @(see INTRODUCTION-TO-REWRITE-RULES-PART-2)
          @(see STRONG-REWRITE-RULES)
              @(see PRACTICE-FORMULATING-STRONG-RULES)
                  @(see PRACTICE-FORMULATING-STRONG-RULES-1)
                  @(see PRACTICE-FORMULATING-STRONG-RULES-2)
                  @(see PRACTICE-FORMULATING-STRONG-RULES-3)
                  @(see PRACTICE-FORMULATING-STRONG-RULES-4)
                  @(see PRACTICE-FORMULATING-STRONG-RULES-5)
                  @(see PRACTICE-FORMULATING-STRONG-RULES-6)
          @(see SPECIFIC-KINDS-OF-FORMULAS-AS-REWRITE-RULES)
          @(see FURTHER-INFORMATION-ON-REWRITING)
      @(see INTRODUCTION-TO-THE-DATABASE)
      @(see INTRODUCTION-TO-HINTS)
      @(see INTRODUCTION-TO-A-FEW-SYSTEM-CONSIDERATIONS)
      @(see INTRODUCTORY-CHALLENGES)
          @(see INTRODUCTORY-CHALLENGE-PROBLEM-1)
          @(see INTRODUCTORY-CHALLENGE-PROBLEM-2)
          @(see INTRODUCTORY-CHALLENGE-PROBLEM-3)
          <i>(there are others but at least do a few)</i>
      @(see FREQUENTLY-ASKED-QUESTIONS-BY-NEWCOMERS)
 </code>

 <p>If any of the links above are marked as ``visited'' by your browser, use
 your browser's tools menu to mark all links as unvisited.  As you can see, we
 really think you'll get the most out of this document if you take it
 seriously.  As you read, you will see some links to ``advanced'' topics.
 These are marked with a tiny warning sign, ``<see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>''.
 They lead out of this linear tutorial and into ACL2's hypertext reference
 manual.  We recommend that you <i>not</i> visit any of these advanced links
 until you have read the entire tutorial at least once.</p>

 <p>After you finish this tutorial material, we recommend that you look at the
 ACL2 Demos, at the ``Demos'' link of the <a
 href='http://www.cs.utexas.edu/users/moore/acl2'>ACL2 home page</a>.</p>

 <p>Many users of ACL2 have bought the book</p>

 <p><i>Computer-Aided Reasoning: An Approach</i>, Kaufmann, Manolios, and
 Moore, Kluwer Academic Publishers, June, 2000</p>

 <p>which is <a href='https://www.lulu.com/shop/j-moore-and-panagiotis-manolios-and-matt-kaufmann/computer-aided-reasoning-an-approach/paperback/product-1p52nnn.html'>
 available in
 paperback</a> from Lulu for approximately $22 (as of 2025).  That book
 contains hundreds of exercises in programming, proof, and using The Method
 described here to prove theorems.  Solutions to the exercises are online, as
 are <a
 href='http://link.springer.com/content/pdf/bbm%3A978-1-4615-4449-4%2F1.pdf'>appendices</a>
 that focus on some practical usage aspects.  See @(see pubs::pubs-books),
 which also includes information about its companion (also available on Lulu)
 describing applications of ACL2, some of which are from industry.</p>

 <p>Using ACL2 is akin to having a partner in the theorem proving enterprise.
 It will do some of the work and you will do some of the work.  It can't really
 be any other way because theorem proving is undecidable.  You bring a quirky,
 error-prone, creative insight to the problem, and ACL2 brings accuracy, logic,
 and perseverance.</p>

 <p>Here we describe a ``model'' of how the system works and introduce some of
 the ideas and terminology you'll use repeatedly when interacting with it.</p>

 <p>This article is about the <i>theorem prover</i> itself, not the programming
 language and not the logic.  We assume you know enough about the ACL2
 programming language that you can define simple functions, run them, and read
 and write ACL2 constants and terms.  For some examples of what we'll take for
 granted about ACL2 programming, see @(see
 programming-knowledge-taken-for-granted).  If you want a brief tutorial on the
 ACL2 programming language see @(see
 gentle-introduction-to-acl2-programming).</p>

 <p>We also assume you know enough about logic to understand, for example, the
 words we use to talk about formulas and proofs.  To see some examples of what
 we'll take for granted about your knowledge of logic terminology, see @(see
 logic-knowledge-taken-for-granted).  If you want an introduction to the ACL2
 logic work your way through @(see recursion-and-induction).</p>

 <p>When you give the theorem prover a goal formula to prove, it tries to prove
 it by breaking it down into subgoals, each of which must be proved in order to
 prove the original goal.  This breaking apart of the goal is done by various
 <i>proof techniques</i> built into ACL2.  Different proof techniques break the
 formula apart in different ways.  For example, the <i>simplifier</i> rips
 apart the propositional structure to isolate the various cases and applies
 rewrite rules to simplify the subterms of the formula, while the
 <i>induction</i> <i>engine</i> will attempt to break the goal into some base
 cases and some induction steps.</p>

 <p>The theorem prover's behavior is affected by a <i>database</i> of
 <i>rules</i> derived from axioms, definitions, and previously proved theorems.
 The database also records the <i>enabled status</i> of each rule; only enabled
 rules are seen by the prover and you can set the status of a rule.  There are
 many other user-settable switches and parameters affecting the behavior of the
 prover; you'll learn about some of them later.</p>

 <p>You guide the theorem prover most of the time simply by identifying lemmas
 for it to prove.  (A <i>lemma</i> is just a theorem that you think is useful
 in the proofs of other theorems.)</p>

 <p>Why does this guide the theorem prover?  Because every time you get the
 system to prove a theorem, it turns the theorem into a rule (unless you tell
 it not to) and stores the rule in the database.  That changes how the prover
 behaves subsequently.  But <i>you</i> determine the kind of rule ACL2
 stores.</p>

 <p>To learn to ``drive'' the theorem prover you have to learn how various
 rules affect the system's behavior and how it turns proved formulas into
 rules.  But before we discuss this, we discuss a more mathematical activity:
 how do you figure out the lemmas ACL2 will need in order for it to prove
 interesting theorems?  ACL2 can often help you in this activity, if you use it
 in the right way.</p>

 <p>Here is the way we recommend you use ACL2.</p>

 <p><b>The Method</b>.</p>

 <p>(1) you present ACL2 with the goal conjecture to prove</p>

 <p>(2) typically, it fails to prove it (or you abort its attempt), but it
 prints some <i>Key Checkpoints</i></p>

 <p>(3) you look at the Key Checkpoints and decide that you know a fact that
 will help; this tutorial will present some helpful questions to keep in
 mind</p>

 <p>(4) you formalize your knowledge as a formula, along with directions for
 how ACL2 should turn the formula into a rule; this tutorial will tell you
 about the most commonly used rule, the <i>rewrite</i> rule</p>

 <p>(5) you recursively apply The Method to get ACL2 to prove your formula and
 to store it as the kind of rule you specified</p>

 <p>(6) go to step (1)</p>

 <p>Caveat: This approach simply won't work on some theorems!  Basically, this
 is a ``troubleshooting'' approach, where you're letting ACL2 determine the
 basic strategy and you're just helping with the subgoals.  But for some
 theorems, ACL2's approach will be misguided and no amount of troubleshooting
 will salvage its strategy.  You'll have a sense that this is happening when it
 happens because the formulas ACL2 presents to you will raise issues that feel
 irrelevant to you.  The basic truth is that if you think a formula is always
 true there are usually strong intuitive reasons behind your belief.  If you
 were asked to defend your belief, you'd start to explain your reasons and with
 training you can turn that into a proof.  So when ACL2's formulas present you
 with things you haven't thought of either (a) you'll have an ``Ah ha!''
 moment when you realize you hadn't considered that case or (b) you'll realize
 that ACL2's approach is different from your intuitive ``proof.''</p>

 <p>But, surprisingly often, the troubleshooting approach to finding proofs
 works quite well, especially as you rein in your expectations and develop a
 sense of what ACL2 can handle on its own.  Of course, if you can decompose the
 proof into a couple of main lemmas before you start, so much the better: write
 down your sequence of lemmas, thinking about the rules you want them to
 generate, and get ACL2 to prove each of them before giving it the main
 theorem.  This <i>proof planning</i> approach will gradually become an
 integral part of your use of The Method.</p>

 <p>The only mechanized help we can offer with The Method, aside from the
 theorem prover itself, are tools to help you manage the stack of subgoals it
 generates when, in step (5) you recursively apply The Method to a lemma.
 There are both Emacs and Eclipse tools available.</p>

 <p>To use The Method you have to read the Key Checkpoints printed at the very
 end of <i>failed</i> proof attempts, just after the line that reads:</p>

 @({
  The key checkpoint goals, below, may help you to debug this failure.
 })

 <p>Most users do not read the output from successful proofs and do not read
 the output <i>during</i> a proof &mdash; they just let it stream by as a sort
 of gestalt meter on the theorem prover's progress or lack thereof.  For
 example, you'll be able to tell it is in a loop and needs to be
 interrupted.</p>

 <p>You will respond to most Key Checkpoints by formulating new lemmas for the
 system to prove and store as rules designed by you to alter ACL2's behavior so
 that it proves the Key Checkpoints.  You will give each lemma a <i>name</i>
 and write some <i>formula</i> to express the mathematical idea.  You'll
 command ACL2 to prove it by typing:</p>

 <code>
 (defthm <i>name</i>
         <i>formula</i>
         ...)
 </code>

 <p>In the ``...'' you may provide two other kinds of information: <i>hints</i>
 for how to prove <i>formula</i> and directives, called <i>rule-classes</i>,
 for how to convert <i>formula</i> into a rule after it has proved
 <i>formula</i>.  Note that <i>you</i> are in charge of determining what kind
 of rule ACL2 generates!  There are over a dozen different types of rules with
 many opportunities to specialize each type.  But the most common kind of rule
 you'll want to generate is a <i>rewrite</i> rule.</p>

 <p>We recommend that you read the following topics in the following order,
 without skipping anything except links into the ACL2 User's Manual, which are
 marked by the little warning sign, ``<see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>''.</p>

 <p>(1) See @(see introduction-to-rewrite-rules-part-1) to read about the use
 and design of rewrite rules.</p>

 <p>(2) See @(see introduction-to-key-checkpoints) to see how to use The Method
 to help you design rules.</p>

 <p>(3) See @(see introduction-to-rewrite-rules-part-2) for general guidance on
 how to turn formulas into effective rules.</p>

 <p>(4) See @(see introduction-to-the-database) to see how to issue commands
 that build different kinds of rules and that affect the enabled status of
 existing rules.</p>

 <p>(5) See @(see introduction-to-hints) to see how to give the prover hints
 for how to prove specific theorems or even subgoals of specific proof
 attempts.</p>

 <p>(6) See @(see introduction-to-a-few-system-considerations) for a few words
 about system aspects of interacting with ACL2.</p>

 <p>(7) See @(see introductory-challenges) for a graduated sequence of good
 challenge problems for the new user to tackle.  <b>Do not skip this
 section!</b> It is here that you <i>really</i> learn how to use ACL2 &mdash;
 by using it.</p>

 <p>(8) See @(see frequently-asked-questions-by-newcomers) for a list of
 questions that new users frequently ask, answered mainly by providing links
 into the ACL2 User's Manual.  We recommend that you skim through these
 questions and remember that you can find the answers here later.  We are very
 interested in receiving suggestions for how to improve this FAQ and this
 tutorial.  See the ACL2 home page, specifically the link ``Mailing
 Lists''.</p>

 <p>Please read all of the material cited above (skipping only the ACL2 User's
 Manual links (``<see topic='ACL2____A_02Tiny_02Warning_02Sign'><icon
 src='res/tours/twarning.gif'/></see>'')) before you try to use ACL2 on problems of your
 own.</p>

 <p>By this point you should have read, at least, the following topics from
 this tutorial introduction to the theorem prover:</p>

 <code>
  @(see INTRODUCTION-TO-THE-THEOREM-PROVER)
      @(see INTRODUCTION-TO-REWRITE-RULES-PART-1)
          @(see SPECIAL-CASES-FOR-REWRITE-RULES)
          @(see EQUIVALENT-FORMULAS-DIFFERENT-REWRITE-RULES)
      @(see INTRODUCTION-TO-KEY-CHECKPOINTS)
          @(see DEALING-WITH-KEY-COMBINATIONS-OF-FUNCTION-SYMBOLS)
          @(see GENERALIZING-KEY-CHECKPOINTS)
          @(see POST-INDUCTION-KEY-CHECKPOINTS)
      @(see INTRODUCTION-TO-REWRITE-RULES-PART-2)
          @(see STRONG-REWRITE-RULES)
              @(see PRACTICE-FORMULATING-STRONG-RULES)
                  @(see PRACTICE-FORMULATING-STRONG-RULES-1)
                  @(see PRACTICE-FORMULATING-STRONG-RULES-2)
                  @(see PRACTICE-FORMULATING-STRONG-RULES-3)
                  @(see PRACTICE-FORMULATING-STRONG-RULES-4)
                  @(see PRACTICE-FORMULATING-STRONG-RULES-5)
                  @(see PRACTICE-FORMULATING-STRONG-RULES-6)
          @(see SPECIFIC-KINDS-OF-FORMULAS-AS-REWRITE-RULES)
          @(see FURTHER-INFORMATION-ON-REWRITING)
      @(see INTRODUCTION-TO-THE-DATABASE)
      @(see INTRODUCTION-TO-HINTS)
      @(see INTRODUCTION-TO-A-FEW-SYSTEM-CONSIDERATIONS)
      @(see INTRODUCTORY-CHALLENGES)
          @(see INTRODUCTORY-CHALLENGE-PROBLEM-1)
          @(see INTRODUCTORY-CHALLENGE-PROBLEM-2)
          @(see INTRODUCTORY-CHALLENGE-PROBLEM-3)
          <i>(there are others but at least do a few)</i>
      @(see FREQUENTLY-ASKED-QUESTIONS-BY-NEWCOMERS)
 </code>

 <p>We also recommend that you look at the ACL2 Demos mentioned in the @(see
 acl2-tutorial).</p>

 <p>Thank you for spending the time to get acquainted with the basics of the
 ACL2 theorem prover.  Don't hesitate to send further questions to the ACL2
 Help address on the ``Mailing Lists'' link of the ACL2 home page.</p>

 <p><b>End of Tutorial Introduction to the Theorem Prover</b></p>

 <p>Below is a list of all of the topics cited on this page.</p>")

(defxdoc introductory-challenge-problem-1
  :parents (introduction-to-the-theorem-prover)
  :short "Challenge problem 1 for the new user of ACL2"
  :long "<p>Start in a fresh ACL2, either by restarting your ACL2 image from
 scratch or executing</p>

 @({
  :ubt! 1
 })

 <p>which will undo everything since the first user event.</p>

 <p>Then define this function:</p>

 @({
  (defun rev (x)
    (if (endp x)
        nil
        (append (rev (cdr x)) (list (car x)))))
 })

 <p>Then use The Method to prove:</p>

 @({
  (defthm triple-rev
    (equal (rev (rev (rev x))) (rev x)))
 })

 <p>When you've solved this problem, compare your answer to ours; see @(see
 introductory-challenge-problem-1-answer).</p>

 <p>Then, use your browser's <b>Back Button</b> to return to @(see
 introductory-challenges).</p>")

(defxdoc introductory-challenge-problem-1-answer
  :parents (introduction-to-the-theorem-prover)
  :short "Answer to challenge problem 1 for the new user of ACL2"
  :long "<p>This answer is in the form of an ACL2 script sufficient to lead
 ACL2 to a proof.</p>

 <code>
 (defun rev (x)
   (if (endp x)
       nil
       (append (rev (cdr x)) (list (car x)))))

 ; Trying @('triple-rev') at this point produces a key checkpoint containing
 ; @('(REV (APPEND (REV (CDR X)) (LIST (CAR X))))'), which suggests:

 (defthm rev-append
   (equal (rev (append a b))
          (append (rev b) (rev a))))

 ; And now @('triple-rev') succeeds.

 (defthm triple-rev
   (equal (rev (rev (rev x))) (rev x)))

 ; An alternative, and more elegant, solution is to prove the @('rev-rev')
 ; instead of @('rev-append'):

 ; (defthm rev-rev
 ;   (implies (true-listp x)
 ;            (equal (rev (rev x)) x)))

 ; @('Rev-rev') is also discoverable by The Method because it is
 ; suggested by the statement of @('triple-rev') itself: @('rev-rev')
 ; simplifies a simpler composition of the functions in @('triple-rev').

 ; Both solutions produce lemmas likely to be of use in future proofs
 ; about @('rev').

 </code>

 <p>Use your browser's <b>Back Button</b> now to return to @(see
 introductory-challenge-problem-1).</p>")

(defxdoc introductory-challenge-problem-2
  :parents (introduction-to-the-theorem-prover)
  :short "Challenge problem 2 for the new user of ACL2"
  :long "<p>Start in a fresh ACL2, either by restarting your ACL2 image from
 scratch or executing @(':ubt! 1').</p>

 <p>Use The Method to prove</p>

 @({
  (defthm subsetp-reflexive
    (subsetp x x))
 })

 <p>When you've solved this problem, compare your answer to ours; see @(see
 introductory-challenge-problem-2-answer).</p>

 <p>Then, use your browser's <b>Back Button</b> to return to @(see
 introductory-challenges).</p>")

(defxdoc introductory-challenge-problem-2-answer
  :parents (introduction-to-the-theorem-prover)
  :short "Answer to challenge problem 2 for the new user of ACL2"
  :long "<p>This answer is in the form of a script sufficient to lead ACL2 to a
 proof.</p>

 <code>
 ; Trying @('subsetp-reflexive') at this point produces the key checkpoint:

 ; (IMPLIES (AND (CONSP X)
 ;               (SUBSETP (CDR X) (CDR X)))
 ;          (SUBSETP (CDR X) X))

 ; which suggests the generalization:

 (defthm subsetp-cdr
   (implies (subsetp a (cdr b))
            (subsetp a b)))

 ; And now @('subsetp-reflexive') succeeds.

 (defthm subsetp-reflexive
   (subsetp x x))

 ; A weaker version of the lemma, namely the one in which we
 ; add the hypothesis that @('b') is a @('cons'), is also sufficient.

 ;    (defthm subsetp-cdr-weak
 ;      (implies (and (consp b)
 ;                    (subsetp a (cdr b)))
 ;               (subsetp a b)))

 ; But the @('(consp b)') hypothesis is not really necessary in
 ; ACL2's type-free logic because @('(cdr b)') is @('nil') if @('b') is
 ; not a @('cons').  For the reasons explained in the tutorial, we
 ; prefer the strong version.

 </code>

 <p>Use your browser's <b>Back Button</b> now to return to @(see
 introductory-challenge-problem-2).</p>")

(defxdoc introductory-challenge-problem-3
  :parents (introduction-to-the-theorem-prover)
  :short "Challenge problem 3 for the new user of ACL2"
  :long "<p>Start in a fresh ACL2, either by restarting your ACL2 image from
 scratch or executing @(':ubt! 1').</p>

 <p>Define the following functions and use The Method to prove the theorem at
 the bottom:</p>

 @({
  (defun rev (x)
    (if (endp x)
        nil
        (append (rev (cdr x)) (list (car x)))))

  (defun dupsp (x)  ; does x contain duplicate elements?
    (if (endp x)
        nil
        (if (member (car x) (cdr x))
            t
            (dupsp (cdr x)))))

  (defthm dupsp-rev
    (equal (dupsp (rev x)) (dupsp x)))
 })

 <p>When you've solved this problem, compare your answer to ours; see @(see
 introductory-challenge-problem-3-answer).</p>

 <p>Then, use your browser's <b>Back Button</b> to return to @(see
 introductory-challenges).</p>")

(defxdoc introductory-challenge-problem-3-answer
  :parents (introduction-to-the-theorem-prover)
  :short "Answer to challenge problem 3 for the new user of ACL2"
  :long "<p>This answer is in the form of a script sufficient to lead ACL2 to a
 proof.</p>

 <code>
 ; Trying @('dupsp-rev') at this point produces the key checkpoint:

 ; (IMPLIES (AND (CONSP X)
 ;               (NOT (MEMBER (CAR X) (CDR X)))
 ;               (EQUAL (DUPSP (REV (CDR X)))
 ;                      (DUPSP (CDR X))))
 ;          (EQUAL (DUPSP (APPEND (REV (CDR X)) (LIST (CAR X))))
 ;                 (DUPSP (CDR X))))

 ; which suggests the lemma

 ; (defthm dupsp-append
 ;   (implies (not (member e x))
 ;            (equal (dupsp (append x (list e)))
 ;                   (dupsp x))))

 ; However, attempting to prove that, produces a key checkpoint
 ; containing @('(MEMBER (CAR X) (APPEND (CDR X) (LIST E)))').
 ; So we prove the lemma:

 (defthm member-append
   (iff (member e (append a b))
        (or (member e a)
            (member e b))))

 ; Note that we had to use @('iff') instead of @('equal') since
 ; @('member') is not a Boolean function.

 ; Having proved this lemma, we return to @('dupsp-append') and succeed:

 (defthm dupsp-append
   (implies (not (member e x))
            (equal (dupsp (append x (list e)))
                   (dupsp x))))

 ; So now we return to @('dups-rev'), expecting success.  But it fails
 ; with the same key checkpoint:

 ; (IMPLIES (AND (CONSP X)
 ;               (NOT (MEMBER (CAR X) (CDR X)))
 ;               (EQUAL (DUPSP (REV (CDR X)))
 ;                      (DUPSP (CDR X))))
 ;          (EQUAL (DUPSP (APPEND (REV (CDR X)) (LIST (CAR X))))
 ;                 (DUPSP (CDR X))))

 ; Why wasn't our @('dupsp-append') lemma applied?  We have two choices here:
 ; (1) Think.  (2) Use tools.

 ; Think: When an enabled rewrite rule doesn't fire even though the
 ; left-hand side matches the target, the hypothesis couldn't be
 ; relieved.  The @('dups-append') rule has the hypothesis @('(not
 ; (member e x))') and after the match with the left-hand side, @('e')
 ; is @('(CAR X)') and @('x') is @('(REV (CDR X))').  So the system
 ; couldn't rewrite @('(NOT (MEMBER (CAR X) (REV (CDR X))))') to true,
 ; even though it knows that @('(NOT (MEMBER (CAR X) (CDR X)))') from
 ; the second hypothesis of the checkpoint.  Obviously, we need to
 ; prove @('member-rev') below.

 ; Use tools:  We could enable the ``break rewrite'' facility, with

 ; ACL2 !&gt;:brr t

 ; and then install an unconditional monitor on the rewrite rule
 ; @('dupsp-append'), whose rune is (:REWRITE DUPSP-APPEND), with:

 ; :monitor (:rewrite dupsp-append) t

 ; Then we could re-try our main theorem, dupsp-rev.  At the resulting
 ; interactive break we type :eval to evaluate the attempt to relieve the
 ; hypotheses of the rule.

 ; (1 Breaking (:REWRITE DUPSP-APPEND) on
 ; (DUPSP (BINARY-APPEND (REV #) (CONS # #))):
 ; 1 ACL2 &gt;:eval

 ; 1x (:REWRITE DUPSP-APPEND) failed because :HYP 1 rewrote to
 ; (NOT (MEMBER (CAR X) (REV #))).

 ; Note that the report above shows that hypothesis 1 of the rule
 ; did not rewrite to T but instead rewrote to an expression
 ; involving @('(member ... (rev ...))').  Thus, we're led to the
 ; same conclusion that Thinking produced.  To get out of the
 ; interactive break we type:

 ; 1 ACL2 &gt;:a!
 ; Abort to ACL2 top-level

 ; and then turn off the break rewrite tool since we won't need it
 ; again right now, with:

 ; ACL2 !&gt;:brr nil

 ; In either case, by thinking or using tools, we decide to prove:

 (defthm member-rev
   (iff (member e (rev x))
        (member e x)))

 ; which succeeds.  Now when we try to prove dups-rev, it succeeds.

 (defthm dupsp-rev
   (equal (dupsp (rev x))
          (dupsp x)))

 </code>

 <p>Use your browser's <b>Back Button</b> now to return to @(see
 introductory-challenge-problem-3).</p>")

(defxdoc introductory-challenge-problem-4
  :parents (introduction-to-the-theorem-prover)
  :short "Challenge problem 4 for the new user of ACL2"
  :long "<p>Start in a fresh ACL2, either by restarting your ACL2 image from
 scratch or executing @(':ubt! 1').</p>

 <p>This problem is much more open ended than the preceding ones.  The
 challenge is to define a function that collects exactly one copy of each
 element of a list and to prove that it returns a subset of the list with no
 duplications.</p>

 <p>(Is this all that one might want to prove?  It is a good idea to think
 about that question, for any application; an answer for this example is at the
 end of this topic.)</p>

 <p><b>Hint</b>: We recommend that you read this hint to align your function
 names with our solution, to make comparisons easier.  Our answer is shown in
 see @(see introductory-challenge-problem-4-answer).  In that page you'll see a
 definition of a function @('collect-once') and the proofs of two theorems:</p>

 @({
  (defthm main-theorem-1-about-collect-once
    (subsetp (collect-once x) x))

  (defthm main-theorem-2-about-collect-once
    (not (dupsp (collect-once x))))
 })

 <p>The function @('dupsp') is as defined in see @(see
 introductory-challenge-problem-3).  This is quite easy.</p>

 <p>Then, we define a tail-recursive version of the method based on the
 pseudo-code:</p>

 @({
   a = nil;
   while (x not empty) {
    a = if (member (car x) a) then a else (cons (car x) a);
    x = (cdr x);
    }
   return a;
 })

 <p>We formalize this with the function @('while-loop-version'), where
 @('(while-loop-version x nil)') is the ``semantics'' of the code above.  I.e.,
 the function @('while-loop-version') captures the while loop in the
 pseudo-code above and returns the final value of @('a'), and it should be
 invoked with the initial value of @('a') being @('nil').</p>

 <p>We prove @('(while-loop-version x nil)') returns a subset of @('x') that
 contains no duplications.  Furthermore, we do it two ways: first
 ``indirectly'' by relating @('while-loop-version') to @('collect-once'), and
 second (``directly'') without using @('collect-once').  Both of these proofs
 are much harder than the @('collect-once') approach, involving about a dozen
 lemmas each.</p>

 <p>Compare your solutions to ours at see @(see
 introductory-challenge-problem-4-answer).</p>

 <p>Then, use your browser's <b>Back Button</b> to return to @(see
 introductory-challenges).</p>

 <p>We conclude this topic by returning to the question posed earlier above: Is
 this all that one might want to prove?  Notice that we didn't prove that every
 element of the given list is indeed an element of the returned list, which
 could be formalized as follows.</p>

 @({
  (thm
    (subsetp x (collect-once x)))
 })")

(defxdoc introductory-challenge-problem-4-answer
  :parents (introduction-to-the-theorem-prover)
  :short "Answer to challenge problem 4 for the new user of ACL2"
  :long "<p>This topic solves a challenge problem presented elsewhere; see
 @(see introductory-challenge-problem-4).  This answer is in the form of a
 script sufficient to lead ACL2 to a proof, with a brief prologue.</p>

 <p>We wish to collect one copy of each element in x.  We'll actually define
 the method two ways, primitive recursively and tail-recursively, the latter
 method being analogous to the program:</p>

 @({
  a = nil;
  while (x not empty) {
    a = if (member (car x) a) then a else (cons (car x) a);
    x = (cdr x);
    }
  return a;
 })

 <p>We'll prove the two ``equivalent'' and we'll prove that they return a
 subset of @('x') that contains no duplications.</p>

 <p>This page is organized into four sections.  (A) We will start by proving
 that the primitive recursive version correct: it returns a subset of its
 argument that is duplication free.  This will be straightforward.  (B) Then
 we'll define the @('while')-loop version and we will prove it ``equivalent''
 to the primitive recursive version.  This will be challenging primarily
 because the two methods collect their answers in different orders; even
 stating the relationship between the two is interesting.  Proving it will
 involve a few lemmas.  But once we prove their ``equivalence'' the correctness
 of the @('while')-loop version will be straightforward from the correctness of
 the primitive recursive version.  (C) We will disable the rules we prove about
 the @('while')-loop version and prove it correct directly, without exploiting
 the primitive recursive version.  This requires leading the theorem prover
 more carefully because reasoning about tail-recursive functions that
 accumulate results is sometimes delicate.  (D) Lessons learned &mdash; a
 narrative that summarizes what we learn from these examples.</p>

 <p>We follow The Method, which, recall, involves us in recursive attempts to
 prove lemmas.  We use a notation to indicate our sequence of proof attempts.
 Here is an example (although in actual use we print things across multiple
 lines).  The number in bracket indicates our ``stack depth''.  The ``key
 term'' is some term from a Key Checkpoint in the failed proof which is
 responsible for our subsequent action.  Sometimes instead of a Key Term we
 just give an English explanation of what we're thinking.</p>

 @({
  [0] (defthm main ...)     Failed!    Key Term: ...
  [1] (defthm lemma-1 ...)  Succeeded!
  [0] (defthm main ...)     Failed!    Key Term: ...
  [1] (defthm lemma-2 ...)  Failed!    Key Term: ...
  [2] (defthm lemma-2a ...) Succeeded!
  [2] (defthm lemma-2b ...) Succeeded!
  [1] (defthm lemma-2 ...)  Succeeded!
  [0] (defthm main ...)     Succeeded!
 })

 <p>The rest of this page is just a re-playable script.</p>

 @({
  ; -----------------------------------------------------------------
  ; Section A:  The Primitive Recursive Version and Its Correctness

  ; The property of having duplications is defined as:

  (defun dupsp (x)
    (if (endp x)
        nil
        (if (member (car x) (cdr x))
            t
            (dupsp (cdr x)))))

  ; The primitive recursive method of collecting one copy of each element is:

  (defun collect-once (x)
    (if (endp x)
        nil
        (if (member (car x) (cdr x))
            (collect-once (cdr x))
            (cons (car x) (collect-once (cdr x))))))

  ; [0]
  (defthm main-theorem-1-about-collect-once
    (subsetp (collect-once x) x))
  ; Succeeded!

  ; [0]
  ; (defthm main-theorem-2-about-collect-once
  ;   (not (dupsp (collect-once x))))
  ; Failed!
  ; Key Term:  (MEMBER (CAR X) (COLLECT-ONCE (CDR X)))

  ; [1]
  (defthm member-collect-once
    (iff (member e (collect-once a))
         (member e a)))
  ; Succeeded!

  ; [0]
  (defthm main-theorem-2-about-collect-once
    (not (dupsp (collect-once x))))
  ; Succeeded!

  ; That was really easy!

  ;-----------------------------------------------------------------
  ; Section B:  The While-Loop Version and Its Correctness --
  ;  presented in two parts:  its equivalence to the primitive recursive
  ;  version and then its correctness proved via that equivalence

  ; The tail-recursive, or while-loop version, is defined as follows.  The
  ; function below is the loop itself and it ought to be called with a = nil to
  ; implement the initialization of a in the pseudo-code above.

  (defun while-loop-version (x a)
    (if (endp x)
        a
        (while-loop-version (cdr x)
                            (if (member (car x) a)
                                a
                                (cons (car x) a)))))

  ; We wish to prove that the two are equivalent.  But they are actually
  ; very different.  For example,

  ; (collect-once '(2 4 1 3 1 2 3 4))           = (1 2 3 4)
  ; (while-loop-version '(2 4 1 3 1 2 3 4) nil) = (3 1 4 2)

  ; Things get a little more complicated if a is non-nil:
  ; (while-loop-version '(2 4 1 3 1 2 3 4) '(2 2 4 4)) = (3 1 2 2 4 4)

  ; Several observations help explain what is happening.  (1) Collect-once
  ; collects the last occurrence of each element, in the order of their last
  ; occurrences.  So, for example, since the last occurrence of 2 precedes the
  ; last occurrence of 3 in '(2 4 1 3 1 2 3 4)), then the collected 2 precedes
  ; the collected 3 in the answer.  But while-loop-version collects the first
  ; occurrence of each element, in the reverse order of that occurrence.  So it
  ; adds 2 to its accumulator first and adds 3 last, making 3 precede 2 in the
  ; answer.

  ; (2) The while-loop-version does not collect anything already in a and indeed
  ; just adds stuff to the front of a, returning everything initially in a plus
  ; one occurrence of everything in x not in a.

  ; To state the relationship that holds between these two we have to define two
  ; other functions.

  ; This is our familiar list reverse function...
  (defun rev (x)
    (if (endp x)
        nil
        (append (rev (cdr x))
                (list (car x)))))

  ; And this function ``removes'' from x all the elements in y, i.e., copies x
  ; while dropping the elements of y.

  (defun list-minus (x y)
    (if (endp x)
        nil
        (if (member (car x) y)
            (list-minus (cdr x) y)
            (cons (car x) (list-minus (cdr x) y)))))

  ; The specific equivalence we're really interested in is
  ; (equal (while-loop-version x nil)
  ;        (collect-once (rev x)))

  ; But we will not be able to prove that by induction because it has the
  ; constant nil where we need a variable, a, in order to admit an appropriate
  ; inductive instance.  So we will attack the most general problem.  What is
  ; (while-loop-version x a) equal to, in terms of collect-once?

  ; The most general relationship between the two collection functions is:

  ; (equal (while-loop-version x a)
  ;        (append (collect-once (list-minus (rev x) a)) a))

  ; This formula bears thinking about!  If you're like us, you won't believe it
  ; until it is proved!

  ; [0]
  ; (defthm general-equivalence
  ;   (equal (while-loop-version x a)
  ;          (append (collect-once (list-minus (rev x) a)) a)))
  ; Failed!
  ; Key term in checkpoint:
  ; (LIST-MINUS (APPEND (REV (CDR X)) (LIST (CAR X))) A)

  ; [1]
  (defthm list-minus-append
    (equal (list-minus (append a b) c)
           (append (list-minus a c)
                   (list-minus b c))))
  ; Succeeded!

  ; [0]
  ; (defthm general-equivalence
  ;   (equal (while-loop-version x a)
  ;          (append (collect-once (list-minus (rev x) a)) a)))
  ; Failed!
  ; Key term in checkpoint:
  ; (COLLECT-ONCE (APPEND (LIST-MINUS (REV (CDR X)) A) (LIST (CAR X))))

  ; [1]
  ; (defthm collect-once-append
  ;   (equal (collect-once (append a b))
  ;          (append (list-minus (collect-once a) b)
  ;                  (collect-once b))))
  ; Failed!
  ; Key term:
  ; (MEMBER (CAR A) (APPEND (CDR A) B))

  ; [2]
  (defthm member-append
    (iff (member e (append a b))
         (or (member e a)
             (member e b))))
  ; Succeeded!

  ; [1]
  (defthm collect-once-append
    (equal (collect-once (append a b))
           (append (list-minus (collect-once a)
                               b)
                   (collect-once b))))
  ; Succeeded!

  ; [0]
  ; (defthm general-equivalence
  ;   (equal (while-loop-version x a)
  ;          (append (collect-once (list-minus (rev x) a)) a)))
  ; Failed!
  ; Key term:
  ; (APPEND (APPEND (LIST-MINUS (COLLECT-ONCE (LIST-MINUS (REV (CDR X)) A))

  ; [1]
  (defthm assoc-append
    (equal (append (append a b) c)
           (append a (append b c))))
  ; Succeeded!

  ; [0]
  ; (defthm general-equivalence
  ;   (equal (while-loop-version x a)
  ;          (append (collect-once (list-minus (rev x) a)) a)))
  ; Failed!
  ; Key term:
  ; (LIST-MINUS (COLLECT-ONCE (LIST-MINUS (REV (CDR X)) A)) ...)

  ; This key term makes us think of the lemma to move the LIST-MINUS inside the
  ; COLLECT-ONCE.  But when that's done, we will have two LIST-MINUS terms
  ; nestled together and we will want to combine them into one.  Call these two
  ; lemmas (a) and (b).

  ; [1] (a)
  ; (defthm list-minus-collect-once
  ;   (equal (list-minus (collect-once x) a)
  ;          (collect-once (list-minus x a))))
  ; Failed!
  ; Key term:
  ; (MEMBER (CAR X) (LIST-MINUS (CDR X) A))

  ; [2] (A pretty fact)
  (defthm member-list-minus
    (iff (member e (list-minus x a))
         (and (member e x)
              (not (member e a)))))
  ; Succeeded!

  ; [1] (a)
  (defthm list-minus-collect-once
    (equal (list-minus (collect-once x) a)
           (collect-once (list-minus x a))))
  ; Succeeded!

  ; [1] (b)
  (defthm list-minus-list-minus
    (equal (list-minus (list-minus x a) b)
           (list-minus x (append b a))))
  ; Succeeded!

  ; [0]
  (defthm general-equivalence
    (equal (while-loop-version x a)
           (append (collect-once (list-minus (rev x) a)) a)))
  ; Succeeded!

  ; That completes the proof of the ``equivalence'' of the two methods.

  ; Now we prove (1) that the result of while-loop-version is a subset, and (2)
  ; that it contains no duplications.  We prove the two conjuncts separately.

  ; [0]
  (defthm main-theorem-1-about-while-loop
    (subsetp (while-loop-version x nil) x))
  ; Succeeded!

  ; But the theorem prover works harder to do the proof above than one might have
  ; expected because it doesn't turn into an instance of
  ; main-theorem-1-about-collect-once because of the presence of the rev term.
  ; However, we're content that ACL2 managed to do the proof on its own.

  ; [0]
  (defthm main-theorem-2-about-while-loop
    (not (dupsp (while-loop-version x nil))))

  ; So we see that the proof of correctness of while-loop-version isn't hard,
  ; after we establish the relationship with the primitive recursive version.
  ; But finding and proving the relationship is fairly challenging.

  ; -----------------------------------------------------------------
  ; Section C:  A Direct Proof of the Correctness of the While-Loop Version

  ; Some would consider the proof in Section B ``indirect'' because we first showed
  ; how while-loop-version could be expressed as a collect-once and then proved
  ; our main theorems about while-loop-version, which means those main proofs
  ; were conducted in terms of collect-once, not while-loop-version.

  ; It is interesting to compare this proof with the ``direct'' one in which
  ; we don't use collect-once at all and reason only about while-loop-version.

  ; So to do that comparison, let's disable all the lemmas we've proved about
  ; while-loop-version and try to prove the two main theorems above about
  ; while-loop-version.

  (in-theory (disable general-equivalence
                      main-theorem-1-about-while-loop
                      main-theorem-2-about-while-loop))

  ; [0]
  ; (defthm main-theorem-1-about-while-loop-redux
  ;   (subsetp (while-loop-version x nil) x))
  ; Failed!  [Well, the truth is below...]

  ; We don't even submit this event above because we recognize that it is not
  ; general enough to permit proof by induction.  We need to deal with the nil in
  ; the second argument of while-loop-version.  Experience with induction tells
  ; us this should be a variable, so we can assume an appropriate inductive
  ; instance.  Therefore, we adopt this subgoal immediately:

  ; [1]
  ; (defthm main-lemma-1-about-while-loop-version
  ;   (subsetp (while-loop-version x a) (append x a)))
  ; Failed!
  ; Key Term:  Does the wrong induction.

  ; [1]
  ; (defthm main-lemma-1-about-while-loop-version
  ;   (subsetp (while-loop-version x a) (append x a))
  ;   :hints (("Goal" :induct (while-loop-version x a))))
  ; Failed!  Two key terms are suggested
  ; Key term: (IMPLIES (AND ... (SUBSETP (WHILE-LOOP-VERSION (CDR X) A) (APPEND (CDR X) A)))
  ;                    (SUBSETP (WHILE-LOOP-VERSION (CDR X) A) (CONS ... (APPEND (CDR X) A))))
  ; Key term: (SUBSETP A A)
  ; So we'll prove both before trying again.
  ; [2]
  (defthm subsetp-cons
    (implies (subsetp a b)
             (subsetp a (cons e b))))
  ; Succeeded!

  ; [2]
  (defthm subsetp-reflexive
    (subsetp a a))
  ; Succeeded!

  ; [1]
  ; (defthm main-lemma-1-about-while-loop-version
  ;   (subsetp (while-loop-version x a) (append x a))
  ;   :hints (("Goal" :induct (while-loop-version x a))))
  ; Failed!
  ; Key Term:
  ; (IMPLIES (AND ...
  ;               (SUBSETP (WHILE-LOOP-VERSION (CDR X) (CONS (CAR X) A))
  ;                        (APPEND (CDR X) (CONS (CAR X) A))))
  ;          (SUBSETP (WHILE-LOOP-VERSION (CDR X) (CONS (CAR X) A))
  ;                   (CONS (CAR X) (APPEND (CDR X) A))))

  ; We'd be done if we could rewrite the
  ; (APPEND (CDR X) (CONS (CAR X) A))
  ; to
  ; (CONS (CAR X) (APPEND (CDR X) A))
  ; These two terms are not equal!  But they are ``set-equal'' and this kind of
  ; rewriting is possible using user-defined equivalences and congruence rules.
  ; But the new user should not dive into congruences yet.  So we will do this
  ; with ordinary lemmas:

  ; The plan then is to prove the rewrite rule
  ; (iff (subsetp a (append b (cons e c)))
  ;      (subsetp a (cons e (append b c))))
  ; in order to rewrite the first call of SUBSETP shown in the key term above
  ; to the second call.

  ; Consider the first half of this bi-implication:
  ; (implies (subsetp a (append b (cons e c)))            ; hyp1
  ;          (subsetp a (cons e (append b c))))           ; concl
  ; Notice that if we knew
  ; (subsetp (append b (cons e c)) (cons e (append b c))) ; hyp2
  ; then we could use hyp1 and hyp2 together with the transitivity of
  ; subsetp to get concl.

  ; The proof in the other direction is comparable but requires the
  ; (subsetp (cons e (append b c)) (append b (cons e c)))

  ; Thus, our plan is prove
  ; (a) transitivity of subsetp
  ; (b) (subsetp (append b (cons e c)) (cons e (append b c)))
  ; (c) (subsetp (cons e (append b c)) (append b (cons e c)))

  ; in order to prove
  ; (d) (iff (subsetp a (append b (cons e c)))
  ;         (subsetp a (cons e (append b c))))

  ; [2] (a)
  (defthm trans-subsetp
    (implies (and (subsetp a b)
                  (subsetp b c))
             (subsetp a c)))
  ; Succeeded!

  ; [2] (b)
  (defthm append-cons-v-cons-append-1
    (subsetp (append b (cons e c))
             (cons e (append b c))))
  ; Succeeded!

  ; [2] (c)
  (defthm append-cons-v-cons-append-2
    (subsetp (cons e (append b c))
             (append b (cons e c))))
  ; Succeeded!

  ; [2] (d)
  (defthm subsetp-append-cons-cons-append
    (iff (subsetp a (append b (cons e c)))
         (subsetp a (cons e (append b c)))))
  ; Succeeded!

  ; [1]
  (defthm main-lemma-1-about-while-loop-version
    (subsetp (while-loop-version x a) (append x a))
    :hints (("Goal" :induct (while-loop-version x a))))
  ; Succeeded!

  ; [0]
  ; (defthm main-theorem-1-about-while-loop-version
  ;   (subsetp (while-loop-version x nil) x))
  ; Failed!  [But the truth is below...]

  ; But we don't submit this because we don't expect it to be proved
  ; from the main lemma just proved:  they don't match!  But
  ; note that if we instantiated the main lemma, replacing a by nil,
  ; we get:

  ; (subsetp (while-loop-version x nil) (append x nil))

  ; and we could simplify the (append x nil) to x in this context, with
  ; another congruence rule -- if we were using them.  So let's prove
  ; first that we can simplify (append x nil) inside a subsetp:

  ; [1]
  (defthm subsetp-append-nil
    (iff (subsetp x (append y nil))
         (subsetp x y)))
  ; Succeeded!

  ; and then just tell ACL2 how to use the lemma to get the main theorem.  Note
  ; that we give a hint to instantiate main-lemma-1... but we also disable
  ; main-lemma-1... because otherwise it will rewrite itself away!  Once the
  ; instance of main-lemma-1... is sitting around as a hypothesis,
  ; subsetp-append-nil will rewrite the (append x nil) to x for us and finish the
  ; proof.

  ; [0]
  (defthm main-theorem-1-about-while-loop-version
    (subsetp (while-loop-version x nil) x)
    :hints (("Goal"
             :use (:instance main-lemma-1-about-while-loop-version
                             (x x)
                             (a nil))
             :in-theory (disable main-lemma-1-about-while-loop-version))))
  ; Succeeded!

  ; Recall that the main-theorem-1... just proved is just half of what we want.
  ; We also want:

  ; [0]
  ; (defthm main-theorem-2-about-while-loop-version
  ;   (not (dupsp (while-loop-version x nil))))
  ; Failed!  [But the truth is below...]

  ; But, again, we don't submit that because the nil makes it not general enough for
  ; induction.  Instead we go immediately to:

  ; [1]
  (defthm main-lemma-2-about-while-loop-version
    (implies (not (dupsp a))
             (not (dupsp (while-loop-version x a)))))
  ; Succeeded!

  ; This time we know our main-lemma-2... will match (there's no (append x nil)
  ; in there to mess things up) and so we can complete the proof with:

  ; [0]
  (defthm main-theorem-2-about-while-loop-version
    (not (dupsp (while-loop-version x nil))))
  ; Succeeded!

  ;-----------------------------------------------------------------
  ; Section D:  Lessons Learned

  ; The most obvious lesson is that it is easier to reason about the primitive
  ; recursive collect-once than about the while-loop-version.  Thus, if your only
  ; need is for a function that collects one occurrence of each element of a list
  ; and you don't care about the order in which you collect them and you don't
  ; need it to be very sparing of stack space when it executes, then use the
  ; primitive recursive definition and don't even think about while loops!

  ; So why might you be driven to while-loop-version?  One possibility is that
  ; the list you wish to process is very long and the primitive recursive version
  ; would produce a stack overflow.  In ACL2, that would mean the list would have
  ; to be several thousand long.  Is your application really so demanding?

  ; Another possibility is that you are modeling in Lisp a while loop expressed
  ; in some other programming language.  In that case, the fidelity of your model to
  ; the artifact being modeled is important and you should use while-loop-version.

  ; Another possibility is that for some reason order matters and you really are
  ; interested in collecting the first occurrence rather than the last.  Of
  ; course this is most likely to be relevant in more interesting applications
  ; where the occurrences are somehow distinguishable.

  ; If you are forced to deal with the while-loop-version the question is do you
  ; do an indirect proof as in Section B or a direct proof as in Section C?
  ; The indirect proof involved 10 theorems and the direct proof involved 11.
  ; That is not a significant difference.

  ; But our sense is that the indirect proof is easier to find, once you figure
  ; out the basic shape of the relation between while-loop-version and
  ; collect-once.  In particular, we had to give the theorem prover two hints
  ; in the direct proof (versus no hints in the indirect proof).  One of our
  ; hints was about what induction to do and the other was about how to use a
  ; previously proved instance of a lemma involving an accumulator.
  ; Furthermore, we had to think carefully about the use of the transitivity of
  ; subsetp and we had to hack our way around rewriting (append a (cons e b))
  ; to (cons e (append a b)) in a subsetp-expression.

  ; Some of these ``set'' problems could have been handled a lot more elegantly
  ; by defining set-equal as an equivalence relation and proving the congruence
  ; rules to allow the rewriting of set-equal terms to set-equal terms inside
  ; certain expressions like subsetp and member.  However, that involves a lot
  ; of overhead in the form of congruence rules showing that set-equality is
  ; maintained by replacement of set-equals by set-equals in various argument
  ; positions of the various functions.  See :doc congruence.  In general, we
  ; find congruence-based reasoning extremely neat and powerful when the
  ; appropriate infrastructure has been built up.  But because the
  ; infrastructure is ``heavy'' we tend not to invest in it for small projects.

  ; In summary, different users might take home different lessons about whether
  ; a direct or indirect proof is better here.  This is in part due to the
  ; complexity of the functional relationship between collect-once and
  ; while-loop-version, which additionally involved append, list-minus, and rev.
  ; Had the relationship been simpler, the indirect proof would have been
  ; preferred.

  ; An undeniable lesson, however, is that it is helpful to know both styles of
  ; proof and to be able to explore both as needed in your applications.
 })

 <p>Use your browser's <b>Back Button</b> now to return to @(see
 introductory-challenge-problem-4).</p>")

(defxdoc introductory-challenges
  :parents (introduction-to-the-theorem-prover)
  :short "Challenge problems for the new ACL2 user"
  :long "<p>Do each of the problems.  In each case, start with a fresh ACL2 (or
 undo all effects of previous events with @(':ubt! 1')).  This may require that
 you ``re-discover'' the same lemma more than once in different problems, but
 recognizing the need for something you used in some previous project is part
 of the training.</p>

 <p>We recommend that you follow The Method and consult the documentation as
 needed &mdash; but that you not look at our answers until you're well and
 truly baffled!</p>

 <p>See @(see introductory-challenge-problem-1) (Answer: @(see
 introductory-challenge-problem-1-answer))</p>

 <p>See @(see introductory-challenge-problem-2) (Answer: @(see
 introductory-challenge-problem-2-answer))</p>

 <p>See @(see introductory-challenge-problem-3) (Answer: @(see
 introductory-challenge-problem-3-answer))</p>

 <p>See @(see introductory-challenge-problem-4) (Answer: @(see
 introductory-challenge-problem-4-answer))</p>

 <p>In addition to these explicit challenge problems designed for beginners,
 the ACL2 documentation has many example solutions to problems (not always
 phrased in the question/answer format here).  If you are looking for other
 examples, you should consider</p>

 <p>@(see annotated-acl2-scripts) (Answer: the answers are given in the
 examples)</p>

 <p>When you've done the problems and compared your solutions to ours, use your
 browser's <b>Back Button</b> now to return to @(see
 introduction-to-the-theorem-prover).</p>")

(defxdoc invariant-risk
  :parents (programming advanced-features guard debugging)
  :short "Potential slowdown for @(see program)-mode updates to @(see stobj)s
 or @(see arrays)"
  :long "<p>You may see a warning like this:</p>

 @({
 ACL2 Warning [Invariant-risk] in MY-FUNCTION:  Invariant-risk has been
 detected for a call of function MY-FUNCTION (as possibly leading to
 an ill-guarded call of UPDATE-FLD); see :DOC invariant-risk.
 })

 <p>Such warnings indicate potential slowdown due to aggressive protection by
 ACL2 against either:</p>

 <ul>

 <li>writing a value of the wrong type to a @(see stobj) field; or</li>

 <li>performing an out-of-bounds write to an ACL2 @(see array).</li>

 </ul>

 <p>Whenever a @(':')@(tsee program)-mode function call can perhaps lead to
 such a write, @(see guard)-checking is performed by ACL2, even though the
 normal expectation is to execute without such checks in Common Lisp; see @(see
 evaluation).  Consider the following example.</p>

 @({
 (defstobj st (fld :type integer :initially 0))

 (defun f (n st)
   (declare (xargs :stobjs st :guard (integerp n)))
   (update-fld n st))

 ; This :program-mode wrapper for f fails to require (integerp n):
 (defun g (n st)
   (declare (xargs :stobjs st :mode :program))
   (f n st))

 ; Produces an invariant-risk warning:
 (g 3 st)

 ; Produces an invariant-risk warning and a guard violation:
 (g 'a st)
 })

 <p>Each of the two calls of @('g') produces an @('"Invariant-risk"')
 warning, and indeed @(see guard)s are checked for the ensuing calls of @('f'),
 causing a guard violation for the second call of @('g').</p>

 <p>We may say that such @(':')@(tsee program)-mode functions have
 invariant-risk.  Because of how the ``aggressive protection'' discussed above
 is implemented, recursive calls of invariant-risk functions are not traced;
 see @(see trace$).</p>

 <p>There are two general methods for avoiding such warnings: at runtime with
 @(tsee set-check-invariant-risk), and at definition time with @(tsee
 set-register-invariant-risk).  We describe each briefly below.  For more
 information follow the links just above to their respective documentation
 topics.  For yet more detail about invariant-risk see @(see
 invariant-risk-details).  For tools that may help find sources of
 invariant-risk, see @(see community-book)
 @('books/std/system/invariant-risk.lisp').</p>

 <h3>Controlling runtime checking for invariant-risk</h3>

 <p>You can avoid seeing warnings like the one displayed above (without
 affecting the check that is actually performed) by evaluating either one of
 the following forms.</p>

 @({
 (set-check-invariant-risk t)
 (set-inhibit-warnings "invariant-risk")
 })

 <p>You can also replace such warnings by errors:</p>

 @({
 (set-check-invariant-risk :error)
 })

 <p>Evaluate @('(get-check-invariant-risk state)') to see the current setting
 for invariant-risk checking.  For details, including a dangerous way to remove
 invariant-risk checking completely at runtime, see @(see
 set-check-invariant-risk).</p>

 <h3>Eliminating invariant-risk checking done by specific functions</h3>

 <p>On occasion you may define functions that you know avoid invariant-risk
 danger, even though ACL2 designates those functions as having invariant-risk.
 Rather than removing invariant-risk checking for <i>all</i> functions at
 runtime with @(tsee set-check-invariant-risk), it is probably much safer to
 remove it only for the functions in a given book or @(tsee encapsulate) event.
 See @(see set-register-invariant-risk) for how to do that.</p>")

(defxdoc invariant-risk-details
  :parents (invariant-risk)
  :short "More details about @(see invariant-risk)"
  :long "<p>This topic, which may be unnecessary for most ACL2 users, expands
 on the documentation for @(see invariant-risk).  See that topic and see @(see
 evaluation) for relevant background.</p>

 <p>We refer below to the following example, which is slightly expanded from
 the one in the documentation for @(see invariant-risk).</p>

 @({
 (defstobj st (fld :type integer :initially 0))

 (defun f1 (n st)
   (declare (xargs :stobjs st :guard (integerp n)))
   (update-fld n st))

 (defun f2 (n st)
   (declare (xargs :stobjs st :guard (integerp n)))
   (f1 n st))

 ; This :program-mode wrapper for f fails to require (integerp n):
 (defun g (n st)
   (declare (xargs :stobjs st :mode :program))
   (f2 n st))

 ; Trace f1 and f2 and their *1* functions.  (This is optional.)
 (trace$ f1 f2 g)

 ; Produces an invariant-risk warning; only *1* functions are called.
 (g 3 st)

 ; Produces an invariant-risk warning and a guard violation:
 (g 'a st)

 ; Defeat invariant-risk checking (risky; uses a trust tag):
 (set-check-invariant-risk nil)

 ; No warning because *1* functions are not called.
 (g 3 st)

 ; No warning because *1* functions are not called.
 (g 'a st)

 ; Non-integer field value!
 (assert-event (equal (fld st) 'a))
 })

 <p>To understand invariant-risk, consider the case that a @(see stobj)
 updater (such as @('update-fld') above) is called on ill-guarded arguments.
 In that case the resulting ACL2 @(see state) could be ill-formed, as in the
 example above: after turning off invariant-risk checking, the stobj @('st') is
 defined to have an integer field yet winds up with a symbol in that field.
 ACL2 arranges invariant-risk checking by installing special code in the
 executable-counterpart of a @(':')@(tsee program)-mode function to prevent it
 from calling its corresponding submitted function.  It does this when the
 @(':program')-mode function has a non-nil @(''invariant-risk') property; in
 the example above, note:</p>

 @({
 ACL2 !>(getpropc 'g 'invariant-risk)
 UPDATE-FLD
 ACL2 !>
 })

 <p>When the function symbol @('g') was defined, it inherited this property
 from @('f2'), which in turn inherited it from @('f1'), which in turn inherited
 it from the stobj updater, @('update-fld').  However, the aforementioned
 special code is only installed for @(':program') mode functions, hence not for
 @('f1') or @('f2').  Consider for example the following trace, from the call
 of @('(g 3)') made above before turning off invariant-risk checking.</p>

 @({
 1> (ACL2_*1*_ACL2::G 3 |<st>|)

 ACL2 Warning [Invariant-risk] in G:  Invariant-risk has been detected
 for a call of function G (as possibly leading to an ill-guarded call
 of UPDATE-FLD); see :DOC invariant-risk.

   2> (ACL2_*1*_ACL2::F2 3 |<st>|)
     3> (F2 3 |<st>|)
       4> (F1 3 |<st>|)
       <4 (F1 |<st>|)
     <3 (F2 |<st>|)
   <2 (ACL2_*1*_ACL2::F2 |<st>|)
 <1 (ACL2_*1*_ACL2::G |<st>|)
 <st>
 ACL2 !>
 })

 <p>This trace illustrates that even though @('f2') has the
 @(''invariant-risk') property, its executable-counterpart has permission to
 call its submitted function because @('f2') is a guard-verified
 @(':logic')-mode function.</p>

 <p>As an optimization, ACL2 avoids setting the @(''invariant-risk') property
 on @(':')@(tsee logic) mode functions whose @(see guard) is @('t') or, more
 generally, a conjunction of @(see stobj) recognizer calls.  For example, the
 call of @('(bar 3 st)') below does not cause an invariant-risk warning.</p>

 @({
 (progn (defstobj st (reg :type (array (unsigned-byte 31) (8))
                          :initially 0))
        (defun foo (i st)
          (declare (xargs :guard t :stobjs st))
          (if (eql i 0) (update-regi i 3 st) st))
        (defun bar (i st)
          (declare (xargs :stobjs st :mode :program))
          (foo i st)))
 (bar 3 st)
 })

 <p>This optimization can hold even if the function is originally submitted
 without guard verification (typically, using @(see xargs) declaration
 @(':verify-guards nil')), but only if its guards are verified before defining the
 @(':program')-mode wrapper (e.g., @('bar') above).  Thus we see an
 invariant-risk warning in the call of @('bar') below.</p>

 @({
 (progn (defstobj st (reg :type (array (unsigned-byte 31) (8))
                          :initially 0))
        (defun foo (i st)
          (declare (xargs :guard t :stobjs st :VERIFY-GUARDS NIL))
          (if (eql i 0) (update-regi i 3 st) st))
        (defun bar (i st)
          (declare (xargs :stobjs st :mode :program))
          (foo i st))
        (verify-guards foo) ; avoid invariant-risk by moving before bar
        )
 (bar 3 st) ; invariant-risk
 })

 <p>Here is code that will return a list of all @(':program')-mode functions
 subject to invariant-risk checking that are user-defined (not built into
 ACL2).</p>

 @({
 :q ; go into raw Lisp
 (let (ans (wrld (w *the-live-state*)))
   (dolist (p (list-all-packages))
     (do-symbols (sym p)
       (when (and (getpropc sym 'invariant-risk)
                  (programp sym wrld)
                  (not (getpropc sym 'predefined)))
         (push sym ans))))
   ans)
 })

 <p>To see exactly the executable-counterpart code generated for a
 @(':program')-mode function with invariant-risk, evaluate
 @('(trace! (oneify-cltl-code :native t))') before submitting its
 definition.</p>")

(defxdoc invisible-fns-table
  :parents (loop-stopper)
  :short "Functions that are invisible to the @(see loop-stopper) algorithm"
  :long "@({
  Examples:
  ACL2 !>(invisible-fns-table (w state))
  ((binary-+ unary--)
   (binary-* unary-/)
   (unary-- unary--)
   (unary-/ unary-/))
 })

 <p>Among other things, the setting above has the effect of making @(tsee
 unary--) ``invisible'' for the purposes of applying permutative @(':')@(tsee
 rewrite) rules to @(tsee binary-+) trees.  Also see @(see add-invisible-fns)
 and see @(see remove-invisible-fns), which manage macro aliases (see @(see
 macro-aliases-table)), as well as see @(see set-invisible-fns-table).</p>

 <p>See @(see table) for a general discussion of tables.</p>

 <p>The ``invisible functions @(see table)'' is an alist with elements of the
 following form, where @('fn') is a function symbol and the @('ufni') are unary
 function symbols in the current ACL2 @(see world), and @('k') is at least
 1.</p>

 @({
  (fn ufn1 ufn2 ... ufnk)
 })

 <p>This @(see table) thus associates with certain function symbols, e.g.,
 @('fn') above, a set of unary functions, e.g., the @('ufni') above.  The
 @('ufni') associated with @('fn') in the invisible functions table are said to
 be ``invisible with respect to @('fn').''  If @('fn') is not the @(tsee car)
 of any pair in the @('alist'), then no function is invisible for it.  Thus for
 example, setting the invisible functions alist to @('nil') completely
 eliminates the consideration of invisibility.</p>

 <p>The notion of invisibility is involved in the use of the @(':')@(tsee
 loop-stopper) field of @(':')@(tsee rewrite) rules to prevent the indefinite
 application of permutative rewrite rules.  Roughly speaking, if rewrite rules
 are being used to permute @('arg') and (ufni arg) inside of a nest of @('fn')
 calls, and @('ufni') is invisible with respect to @('fn'), then @('arg') and
 @('(ufni arg)') are considered to have the same ``weight'' and will be
 permuted so as to end up as adjacent tips in the @('fn') nest.  See @(see
 loop-stopper).</p>")

(defxdoc io
  :parents (interfacing-tools state programming)
  :short "Input/output facilities in ACL2"
  :long "@({
  Example:
  (mv-let
    (channel state)
    (open-input-channel "foo.lisp" :object state)
    (mv-let (eofp obj state)
            (read-object channel state)
            (.
              .
               (let ((state (close-input-channel channel state)))
                     (mv final-ans state))..)))
 })

 <p>Also see @(see std/io) and @(see file-reading-example).</p>

 <p>For advanced ways to control printing, see @(see print-control).</p>

 <p>For a discussion of formatted printing, see @(see fmt).</p>

 <p>To control ACL2 abbreviation (``evisceration'') of objects before printing
 them, see @(see set-evisc-tuple), see @(see without-evisc), and see @(see
 set-iprint).</p>

 <p>To redirect output to a file, see @(see output-to-file).</p>

 <p>ACL2 supports input and output facilities equivalent to a subset of those
 found in Common Lisp.  ACL2 does not support random access to files (with one
 exception: see @(see read-file-into-string)) or bidirectional streams.  In
 Common Lisp, input and output are to or from objects of type @('stream').  In
 ACL2, input and output are to or from objects called ``channels,'' which are
 actually symbols.  Although a channel is a symbol, one may think of it
 intuitively as corresponding to a Common Lisp stream.  Channels are in one of
 two ACL2 packages, @('"ACL2-INPUT-CHANNEL"') and
 @('"ACL2-OUTPUT-CHANNEL"').  When one ``opens'' a file one gets back a
 channel whose @(tsee symbol-name) is the file name passed to ``open,''
 postfixed with @('-n'), where @('n') is a counter that is incremented every
 time an open or close occurs.</p>

 <p>There are three channels which are open from the beginning and which cannot
 be closed:</p>

 @({
    acl2-input-channel::standard-character-input-0
    acl2-input-channel::standard-object-input-0
    acl2-input-channel::standard-character-output-0
 })

 <p>All three of these are really Common Lisp's @('*standard-input*') or
 @('*standard-output*'), appropriately.</p>

 <p>For convenience, three global variables are bound to these rather tedious
 channel names:</p>

 @({
    *standard-ci*
    *standard-oi*
    *standard-co*
 })

 <p>Common Lisp permits one to open a stream for several different kinds of
 @('io'), e.g. character or byte.  ACL2 permits an additional type called
 ``object''.  In ACL2 an ``io-type'' is a keyword, either @(':character'),
 @(':byte'), or @(':object').  When one opens a file, one specifies a type,
 which determines the kind of io operations that can be done on the channel
 returned.  The types @(':character') and @(':byte') are familiar.  Type
 @(':object') is an abstraction not found in Common Lisp.  An @(':object') file
 is a file of Lisp objects.  One uses @('read-object') or
 @('read-object-with-case') (see below) to read from @(':object') files and
 @(tsee print-object$), its more flexible variant @(tsee print-object$+), or
 @('print-object$-preserving-case') (see below; also, @('print-object$-fn')) to
 print to @(':object') files.  (The reading and printing are really done with
 the Common Lisp @('read') and printing functions.  For those familiar with
 @('read'), we note that the @('recursive-p') argument is @('nil').)  The
 function @('read-object-suppress') is logically the same as @('read-object')
 except that @('read-object-suppress') throws away the second returned value,
 i.e. the value that would normally be read, simply returning @('(mv eof
 state)'); under the hood, @('read-object-suppress') avoids errors, for example
 those caused by encountering symbols in packages unknown to ACL2.</p>

 <p>The functions @('read-object-with-case') is defined logically simply to be
 @('read-object'), while the function @('print-object$-preserving-case') and
 macro @(tsee print-object$+) are defined logically simply to be
 @('print-object$').  However, these variants generally do I/O
 differently (except that when the host Lisp is GCL,
 @('print-object$-preserving-case') behaves the same as @('print-object$')).
 For @('read-object-with-case') the value that is read is affected by an extra
 argument, namely, the second argument: the <i>mode</i>.  The mode is one of
 the keywords @(':upcase'), @(':downcase'), @(':preserve'), or @(':invert'),
 where @(':upcase') gives the same behavior as @('read-object'), and the other
 three modes are handled according to the specification for the Common Lisp
 function, @('readtable-case') (see for example <a
 href='http://www.lispworks.com/documentation/HyperSpec/Body/23_aba.htm'>the
 Common Lisp HyperSpec's documentation for ``Examples of Effect of Readtable
 Case on the Lisp Reader''</a>).  The function
 @('print-object$-preserving-case') is somewhat analogous: it is defined
 logically to be @('print-object$') and it has the same behavior, except that
 symbols are printed without adding escapes merely because of lowercase
 letters; for example, the symbol in the current package with name @('"abc"')
 will be printed as @('abc'), not as @('|abc|').  But note that
 @('print-object$-preserving-case') may still insert vertical bars, depending
 on the host Lisp, because different Lisp implementations choose to escape
 symbols differently.  Consider the symbol typically printed as @('|1u|').
 Using @('print-object$-preserving-case'), this prints simply as @('1u') in CCL
 and Allegro CL, but it is printed as @('|1u|') in SBCL, LispWorks, and CMUCL
 &mdash; at least in the implementations that we tested!</p>

 <p>@('File-name') arguments are strings (except for the @(':STRING') case
 discussed below).  ACL2 does not support the Common Lisp type @(tsee
 pathname); rather, the underlying host Lisp will interpret the given string as
 a pathname.  If the string represents a relative pathname, it will be
 elaborated to a full pathname using the connected book directory; see @(see
 cbd).  You can do that elaboration yourself with a directory @('dir') using
 @('(extend-pathname dir file-name state)'); see @(see extend-pathname).</p>

 <p>For the @('file-name') argument of the output-related functions listed
 below, ACL2 supports a special value, @(':STRING').  For this value, the
 channel connects (by way of a Common Lisp output string stream) to a string
 rather than to a file: as characters are written to the channel they can be
 retrieved by using @('get-output-stream-string$').</p>

 <p>Here are the names, formals and output descriptions of the ACL2 io
 functions.</p>

 @({
  Input Functions:
    (open-input-channel (file-name io-type state) (mv channel state))
    (open-input-channel-p (channel io-type state) boolean)
    (close-input-channel (channel state) state)
    (read-char$ (channel state) (mv char/nil state)) ; nil for EOF
    (peek-char$ (channel state) char/nil)
    (read-byte$ (channel state) (mv byte/nil state)) ; nil for EOF
    (read-object (channel state) (mv eof-read-flg obj-read state))
    (read-object-with-case (channel mode state) (mv eof-read-flg obj-read state))
    (read-object-suppress (channel state) (mv eof-read-flg state))
    (read-file-into-string (file-name &key..) string/nil) ; macro (reads state)

  Output Functions:
    (open-output-channel  (file-name io-type state) (mv channel state))
    (open-output-channel! (file-name io-type state) (mv channel state))
    (open-output-channel-p (channel io-type state) boolean)
    (close-output-channel (channel state) state)
    (princ$ (obj channel state) state)
    (write-byte$ (byte channel state) state)
    (print-object$ (obj channel state) state)
    (print-object$+ (obj channel &key ...) state)
    (print-object$-preserving-case (obj channel state) state)
    (print-object$-fn (obj serialize-character channel state) state)
    (fms  (string alist channel state evisc-tuple) state)
    (fms! (string alist channel state evisc-tuple) state)
    (fmt  (string alist channel state evisc-tuple) (mv col state))
    (fmt! (string alist channel state evisc-tuple) (mv col state))
    (fmt1 (string alist col channel state evisc-tuple) (mv col state))
    (fmt1! (string alist col channel state evisc-tuple) (mv col state))
    (cw (string arg0 arg1 ... argn) nil)
    (get-output-stream-string$ (channel state
                                &optional (close-p 't)
                                          (ctx ''get-output-stream-string$))
                               (mv erp string state))
 })

 <p>Note that @('open-output-channel') and @('open-output-channel!') will
 attempt to create directories as needed (but this is not the case for
 @('open-input-channel')).  For example, the following can succeed in writing
 to the indicated file by creating subdirectory @('"dir4"') if that directory
 does not already exist.</p>

 @({
 (mv-let
   (channel state)
   (open-output-channel "dir4/foo4" :object state)
   (pprogn (fms "Here: ~x0"
                (list (cons #\0 (make-list 10)))
                channel state nil)
           (close-output-channel channel state)))
 })

 <p>The ``formatting'' functions are particularly useful; see @(see fmt) and
 see @(see cw).  In particular, @(tsee cw) prints to a ``comment window'' and
 does not involve the ACL2 @(tsee state), so many may find it easier to use
 than @(tsee fmt) and its variants.  The functions @(tsee fms!), @(tsee fmt!),
 and @(tsee fmt1!) are the same as their respective functions without the
 ``@('!'),'' except that the ``@('!')'' functions are guaranteed to print forms
 that can be read back in (at a slight readability cost).</p>

 <p>When one enters ACL2 with @('(lp)'), input and output are taken from @(tsee
 *standard-oi*) to @(tsee *standard-co*).  Because these are synonyms for
 @('*standard-input*') and @('*standard-output*'), one can drive ACL2 io off of
 arbitrary Common Lisp streams, bound to @('*standard-input*') and
 @('*standard-output*') before entry to ACL2.</p>

 <p>The macro @('get-output-stream-string$') returns the string accumulated
 into the given channel.  By default, a call of this macro closes the supplied
 output channel.  However, a third argument is optional (default @('t')), and
 if it evaluates to @('nil') then the channel remains open.  The fourth
 argument is an optional context, which generally evaluates to a symbol, for
 error reporting.  The following example illustrates.</p>

 @({
  ACL2 !>
  (mv-let
     (channel state)
     (open-output-channel :string :object state)
     (pprogn (print-object$-fn 17 nil channel state)
             (print-object$-fn '(a b (c d)) nil channel state)
             (er-let*
               ((str1 (get-output-stream-string$
                       channel state
                       nil))) ; keep the channel open
               (pprogn (print-object$-fn 23 nil channel state)
                       (print-object$-fn '((e f)) nil channel state)
                       (er-let* ; close the channel
                         ((str2 (get-output-stream-string$ channel state)))
                         (value (cons str1 str2)))))))
   ("
  17
  (A B (C D))" . "
  23
  ((E F))")
  ACL2 !>
 })

 <p>Also see @(see printing-to-strings) for a discussion of formatted printing
 functions such as @('fmt-to-string') that do not take a channel or @(tsee
 state) argument and return a string.</p>

 <p>By default, symbols are printed in upper case when vertical bars are not
 required, as specified by Common Lisp.  See @(see set-print-case) for how to
 get ACL2 to print symbols in lower case.</p>

 <p>By default, numbers are printed in radix 10 (base 10).  See @(see
 set-print-base-radix) for how to get ACL2 to print numbers in radix 2, 8, or
 16.</p>

 <p>To see the @(see guard) of an IO function, or indeed any function, see
 @(see args) or call the function @('guard'); but some built-in functions
 (including some IO functions) will print the result using the variable
 @('STATE-STATE').  While that is logically correct, if you want to execute the
 guard then you should replace that variable by @('STATE') and also replace
 each built-in function symbol of the form @('xxx-p1') by corresponding
 function symbol @('xxx-p').  Consider the following example.</p>

 @({
  ACL2 !>:args princ$

  Function         PRINC$
  Formals:         (X CHANNEL STATE-STATE)
  Signature:       (PRINC$ * * STATE)
                   => STATE
  Guard:           (AND (OR (ACL2-NUMBERP X)
                            (CHARACTERP X)
                            (STRINGP X)
                            (SYMBOLP X))
                        (STATE-P1 STATE-STATE)
                        (SYMBOLP CHANNEL)
                        (OPEN-OUTPUT-CHANNEL-P1 CHANNEL
                                                :CHARACTER STATE-STATE))
  Guards Verified: T
  Defun-Mode:      :logic
  Type:            (CONSP (PRINC$ X CHANNEL STATE-STATE))
  Documentation available via :DOC
   PRINC$
  ACL2 !>(untranslate (guard 'princ$ nil (w state)) t (w state))
  (AND (OR (ACL2-NUMBERP X)
           (CHARACTERP X)
           (STRINGP X)
           (SYMBOLP X))
       (STATE-P1 STATE-STATE)
       (SYMBOLP CHANNEL)
       (OPEN-OUTPUT-CHANNEL-P1 CHANNEL
                               :CHARACTER STATE-STATE))
  ACL2 !>
 })

 <p>If you want to execute the guard for @(tsee princ$), then according to the
 suggestion above, you should consider the guard for @('(princ$ x channel
 state)') to be as follows.</p>

 @({
  (AND (OR (ACL2-NUMBERP X)
           (CHARACTERP X)
           (STRINGP X)
           (SYMBOLP X))
       (STATE-P STATE)
       (SYMBOLP CHANNEL)
       (OPEN-OUTPUT-CHANNEL-P CHANNEL :CHARACTER STATE))
 })

 <p>For example, we can check the guard for a given value and channel as
 follows.</p>

 @({
  ACL2 !>(let ((x 3) (channel *standard-co*))
           (AND (OR (ACL2-NUMBERP X)
                    (CHARACTERP X)
                    (STRINGP X)
                    (SYMBOLP X))
                (STATE-P STATE)
                (SYMBOLP CHANNEL)
                (OPEN-OUTPUT-CHANNEL-P CHANNEL :CHARACTER STATE)))
  T
  ACL2 !>
 })

 <p>Comment for advanced users: Function @(tsee open-output-channel!) is
 identical as a function to @('open-output-channel'), except that the former
 may be called even during @(tsee make-event) expansion and @(tsee
 clause-processor) @(see hints), but requires that there is an active trust tag
 (see @(see defttag)).</p>

 <p>Finally, we note that the @(see std/io) library contains useful file io
 functions whose definitions illustrate some of the features described above,
 as does the definition of @(tsee write-list) in @(see community-book)
 @('books/misc/file-io.lisp').</p>")

(defxdoc irrelevant-formals
  :parents (programming)
  :short "Formals that are used but only insignificantly"
  :long "<p>Let @('fn') be a function of @('n') arguments.  Let @('x') be the
 @('i')th formal of @('fn').  We say @('x') is ``irrelevant in @('fn')'' if
 @('x') does not occur in either the @(see guard) or the measure for @('fn'),
 and the value of @('(fn a1...ai...an)') is independent of @('ai').</p>

 <p>The easiest way to define a function with an irrelevant formal is simply
 not to use the formal anywhere in its definition.  Such formals are said to be
 ``ignored'' by Common Lisp and a special declaration is provided to allow
 ignored formals.  ACL2 makes a distinction between ignored and irrelevant
 formals.  Note however that if a variable is @(tsee declare)d @('ignore')d or
 @('ignorable'), or if it occurs free in an @(tsee xargs) term associated with
 @(':')@(see measure), @(':')@(see guard), or @(':')@(tsee split-types), then
 it will not be reported as irrelevant.</p>

 <p>An example of an irrelevant formal is @('x') in the definition of @('fact')
 below.</p>

 @({
  (defun fact (i x)
    (declare (xargs :guard (and (integerp i) (<= 0 i))))
    (if (zp i) 1 (* i (fact (1- i) (cons i x))))).
 })

 <p>Observe that @('x') is only used in recursive calls of @('fact'); it never
 ``gets out'' into the result.  ACL2 can detect some irrelevant formals by a
 closure analysis on how the formals are used; let us call these the ``clearly
 irrelevant formals.''  For example, if the @('i')th formal is only used in the
 @('i')th argument position of recursive calls, then it is clearly irrelevant.
 This is how @('x') is used above.</p>

 <p>It is possible for a formal to appear only in recursive calls but not be
 clearly irrelevant, or even irrelevant at all.  For example, @('x') is
 <b>not</b> irrelevant below, even though it only appears in the recursive
 call.</p>

 @({
  (defun fn (i x y)
    (if (zp i) y (fn (1- i) y x)))
 })

 <p>The following examples show the relevance of @('x').</p>

 @({
 ACL2 !>(fn 1 3 0)
 3
 ACL2 !>(fn 1 4 0)
 4
 ACL2 !>
 })

 <p>The key observation for the definition of @('fn') is that while @('x') only
 appears in a recursive call, it appears in the argument position for a formal
 that is not clearly irrelevant, namely @('y')'s.</p>

 <p>Establishing that a formal is irrelevant, in the sense defined above, can
 be an arbitrarily hard problem because it requires theorem proving.  For
 example, is @('x') irrelevant below?</p>

 @({
  (defun test (i j k x) (if (p i j k) 0 x))
 })

 <p>Note that the value of @('(test i j k x)') is independent of @('x') &mdash;
 thus making @('x') irrelevant &mdash; precisely if @('(p i j k)') is a
 theorem.  ACL2's syntactic analysis of a definition to determine the ``clearly
 irrelevant'' formals does not guarantee to notice all irrelevant formals.</p>

 <p>We regard the presence of irrelevant formals as an indication that
 something is wrong with the definition.  By default, ACL2 causes an error on
 such definitions.  In most cases the best remedy for such an error is to
 recode the definition so as to eliminate the irrelevant formals.  Another
 option is to @(tsee declare) the irrelevant formals, for example as
 follows.</p>

 @({
  (defun fact (i x)
    (declare (irrelevant x))
    (if (zp i) 0 (* i (fact (1- i) (cons i x)))))
 })

 <p>Note that an @('irrelevant') declaration is only legal for a @(tsee
 defun) form, not in other contexts that allow declarations (@(tsee let),
 etc.).</p>

 <p>To turn off the checking of irrelevant formals globally (though we do not
 recommend avoiding those checks), see @(see set-irrelevant-formals-ok).  In
 that case ACL2 will ignore every @('irrelevant') declaration.  But otherwise,
 and by default, if you provide an @('irrelevant') declaration (see @(see
 declare)), then it must specify exactly the formals that ACL2 determines to be
 irrelevant, what we call the ``clearly irrelevant'' formals above: any formal
 declared irrelevant that is not clearly irrelevant will cause an error.</p>")

(defxdoc keep
  :parents (books-tour)
  :short "How we know if @(tsee include-book) read the correct files"
  :long "<p>The certificate (see @(see certificate) for general information) of
 a certified file contains a @(see portcullis) and a keep.  These names come
 from castle lore.  The keep is the strongest and usually tallest tower of a
 castle from which the entire courtyard can be surveyed by the defenders.  The
 keep of a book is a list of file names and @(see book-hash) values used after
 the book has been included, to determine if the files read were (up to
 book-hash) those certified.</p>

 <p>Once the @(see portcullis) is open, @(tsee include-book) can enter the book
 and read the event forms therein.  The non-@(tsee local) event forms are in
 fact executed, extending the host theory.  That may read in other @(see
 books).  When that has been finished, the keep of the @(see certificate) is
 inspected.  The keep is a list indicating all of the included
 books (hereditarily through all sub-books) in the certified book (including
 the certified book itself) together with the @(see book-hash) values for those
 @(see books) at the time of certification.  We compare the book-hash values of
 the @(see books) just included to those of the @(see books) stored in the
 keep.  If differences are found then we know that the book or one of its
 sub-books has been changed since certification.</p>

 <p>See @(see include-book) to continue the guided tour through @(see
 books).</p>")

(defxdoc keyword-commands
  :parents (ld)
  :short "How keyword commands like @(':u') and @(':pbt') are processed"
  :long "@({
  Examples:
  user type-in                 form evaluated
  :pc 5                        (ACL2::PC '5)
  :pcs app rev                 (ACL2::PCS 'app 'rev)
  :length (1 2 3)              (ACL2::LENGTH '(1 2 3))
  :quit                        (ACL2::QUIT) ; Note: avoid optional argument
 })

 <p>When a keyword, @(':key'), is read as a command, ACL2 determines whether
 the symbol with the same name in the @('"ACL2"') package, @('acl2::key'), is
 a function or simple macro of n arguments.  If so, ACL2 reads @('n') more
 objects, @('obj1'), ..., @('objn'), and then acts as though it had read the
 following form (for a given @('key')):</p>

 @({
  (ACL2::key 'obj1 ... 'objn)
 })

 <p>Thus, by using the keyword command hack you avoid typing the parentheses,
 the @('"ACL2"') package name, and the quotation marks.</p>

 <p>See @(see ld-keyword-aliases) for how to customize this behavior.</p>

 <p>Note the generality of this hack.  Any function or macro in the
 @('"ACL2"') package can be so invoked, not just ``commands.''  Indeed, there
 is no such thing as a distinguished class of commands.  Users may take
 advantage of the keyword command hack by defining functions and macros in the
 @('"ACL2"') package.</p>

 <p>The one caveat is that when the keyword hack is used to invoke a macro,
 only the required arguments for that macro are read before calling that macro:
 none of the @('&optional'), @('&rest'), @('&body'), or @('&key') arguments are
 read for that call.  The macro is thus called with only its required
 arguments.  The following log illustrates this caveat.</p>

 @({
  ACL2 !>:set-iprint t

  ACL2 Query (:SET-IPRINT):  Action  (T, NIL, RESET, RESET-ENABLE, SAME,
  Q or ?):
  ACL2 Observation in SET-IPRINT:  Iprinting has been enabled.
  ACL2 !>
 })

 <p>What happened?  First, the command @(':set-iprint') was read.  Since the
 macro @(tsee set-iprint) has no required arguments, the ACL2 evaluator was
 then called on the form @('(set-iprint)'), that is, calling the macro on no
 arguments.  @('Set-iprint') is defined to query the ACL2 user when its first
 argument is omitted.  The log shows that query, which is set up to read the
 next form from the input stream.  That form was available immediately: the
 form @('t') that had been supplied by the user.  So the query returned
 immediately and the @('set-iprint') call was completed.</p>")

(defxdoc keyword-listp
  :parents (lists keywordp acl2-built-ins)
  :short "Recognizer for true lists of keywords"
  :long "<p>The call @('(keyword-listp x)') return @('t') when @('x') is a
 true-list whose members are all @(see keyword)s, else returns @('nil').</p>")

(defxdoc keyword-value-listp
  :parents (keywordp lists acl2-built-ins)
  :short "Recognizer for true lists whose even-position elements are keywords"
  :long "<p>@('(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 list the keys @('ki') and values @('ai') of @('l')
 evaluate @('(evens l)') and @('(odds l)'), respectively.</p>

 @(def keyword-value-listp)")

(defxdoc keywordp
  :parents (symbols acl2-built-ins)
  :short "Recognizer for keywords"
  :long "<p>@('(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 @(tsee symbol-name) of the symbol.</p>

 <p>@('Keywordp') has a @(see guard) of @('t').</p>

 <p>@('Keywordp') is a Common Lisp function.  See any Common Lisp documentation
 for more information.  The following log may be illuminating.</p>

 @({
  ACL2 !>(intern "ABC" "KEYWORD")
  :ABC
  ACL2 !>(symbol-name ':ABC)
  "ABC"
  ACL2 !>(symbol-package-name ':ABC)
  "KEYWORD"
  ACL2 !>
 })

 @(def keywordp)")

(defxdoc kwote
  :parents (term acl2-built-ins)
  :short "Quote an arbitrary object"
  :long "<p>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').</p>

 @(def kwote)")

(defxdoc kwote-lst
  :parents (term acl2-built-ins)
  :short "Quote an arbitrary true list of objects"
  :long "<p>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)').</p>

 @(def kwote-lst)")

(defxdoc l<
  :parents (term apply$)
  :short "Ordering on naturals or lists of naturals"
  :long "<p>The function @('l<') is a straightforward ordering relation that
 compares two objects, each of which is a natural number or a list of natural
 numbers.  It may be convenient to apply @('lex-fix') to two objects before
 comparing them with @('l<').  Below are the relevant definitions.</p>

 @(def l<)
 @(def lexp)
 @(def d<)
 @(def lex-fix)
 @(def nfix-list)")

(defxdoc lambda
  :parents (term apply$)
  :short "Lambda expressions, @('LAMBDA') objects, and @('lambda$') expressions"
  :long "<p>The word ``lambda'' occurs in several different contexts in ACL2.
  When we are being precise our meanings are as outlined below.</p>

  <ul>

  <li>lambda expression -- This phrase is used to describe the syntactic
  entity beginning with the symbol @('lambda') that is allowed to occupy the
  ``function'' position in an ACL2 @(see term).  Lambda expressions are most
  often created when @('let') expressions are translated into their formal
  counterparts.  We provide an example below.</li>

  <li>@('LAMBDA') object -- An ACL2 list constant interpreted as a ``function''
  by @(tsee apply$).  @('LAMBDA') objects may be written in terms by quoting them.
  However, we urge the user to introduce @('LAMBDA') objects into terms by using
  the built-in macro @(tsee lambda$).  We provide examples below.</li>

  <li>@('lambda$') expressions -- These are untranslated terms beginning with
  the macro symbol @('lambda$').  They expand during translation to quoted @('LAMBDA')
  objects.  We provide examples below.</li>

  </ul>

  <p>These three phrases are very similar but mean very different things.  You
  should read carefully when you see us talk about lambda things!
  Unfortunately, we're not always as precise as we might be so you might have
  to disambiguate our usage by context.  If you see places in the documentation
  where you think we've messed up, please bring them to our attention!</p>

  <h3>About Lambda Expressions</h3>

  <p>Consider the function @('odd-evenp'), defined with</p>

  @({
  (defun odd-evenp (x)
    (if (zp x)
        -1
        (let ((ans (odd-evenp (- x 1))))
          (* (+ ans 1) (- ans 1)))))
  })

  <p>Distracting Aside: Can you see why we gave this function this name?  Hint:
  We might have named it ``weird @('evenp').''</p>

  <p>The translated body of @('odd-evenp') is</p>

  @({
  (if (zp x)
      '-1
      ((lambda (ans)
               (binary-* (binary-+ ans '1)
                         (binary-+ '-1 ans)))
       (odd-evenp (binary-+ '-1 x))))
  })

  <p>The syntactic entity in the function position of the term in the false
  branch, namely</p>

  @({
  (lambda (ans)
    (binary-* (binary-+ ans '1)
              (binary-+ '-1 ans)))
  })

  <p>is a lambda expression.</p>

  <p>Lambda expressions are integral to the formal representation of terms.
  They are the formal mechanism by which local variables are introduced and
  thus allow repeated references to intermediate results without causing
  recomputation.  In ACL2 they obey the rules of Common Lisp.  In particular,
  while defining a recursive function it is allowed to call the function
  recursively within the lambda expression, e.g., to temporarily save the value
  of a recursive call for repeated use.  (This is not illustrated by
  @('odd-evenp') where the recursive call is outside of the lambda expression.)
  For more details on the formal representation of ACL2 terms, see @(see
  term).</p>

  <h3>About @('LAMBDA') Objects</h3>

  <p>Prior to Version  8.0 when @('apply$') was introduced, ``lambda
  expression'' was the only phrase the ACL2 developers used mentioning the word
  ``lambda.''  Some Community Books introduced various terms or objects
  mentioning the word but that is beyond the scope of this documentation.
  Because ``lambda'' occurred in no other context before @('apply$') we are not
  confident that every reference to what we are now calling ``lambda
  expressions'' were called by that precise phrase in old documentation.
  If you see a place where we refer to these entities by another phrase, please
  let us know!</p>

  <p>When @(tsee apply$) was introduced, @('LAMBDA') objects became a formally
  supported concept in the ACL2 implementation and we started using
  ``@('LAMBDA') objects'' to refer to them.  A @('LAMBDA') object is generally
  a list, either of the form @('(LAMBDA vars body)') or @('(LAMBDA vars dcl
  body)').  There are additional restrictions on @('vars'), @('dcl'), and
  @('body') that we discuss later.  But @('apply$') treats any @('consp')
  object and tries to extract those components by rudimentary pattern matching.
  An example of a @('LAMBDA') object is the list of length three
  @('(LAMBDA (x) (BINARY-+ '1 X))').</p>

  <p>Generally speaking when @('LAMBDA') objects occur in translated terms they
  are @('quote')d, as in</p>

  @({
  (collect$ '(LAMBDA (X) (BINARY-+ '1 X)) lst)
  })

  <p>To highlight the fact that these objects are constants, we try to write
  them in UPPERCASE and @('typewriter') font in this documentation.  For the
  same reason, we generally write ``@('LAMBDA') object'' rather than ``lambda
  object.''</p>

  <p>But of course there's no difference between the symbol @('LAMBDA') and the
  symbol @('lambda').  Furthermore, @('LAMBDA') objects need not be quoted.
  From a logical perspective they could just be consed up because they are just
  ordinary ACL2 list constants.  Their ``lambda'' status comes from being
  treated as functions by @('apply$').  So one could write</p>

  @({
  (collect$ (list 'lambda '(x) '(binary-+ '1 x)) lst)
  })

  <p>and we would say that the value of the term in the first argument of
  @('collect$') is a @('LAMBDA') object.</p>

  <p>Beware, however, that consing up @('LAMBDA') objects defeats the @(see
  ilk) analysis in @(tsee defwarrant) and the @(see tame)ness analysis of
  @('apply$') and hence prevents functions containing such terms from being
  @('apply$')d.</p>

  <p>According to the definitional axiom defining @(tsee apply$), any object
  satisfying @('consp') is treated as a @('LAMBDA') object.  @('Apply$') uses
  ``accessor'' functions to extract the ``formals'' and ``body'' of the object
  and proceeds to @(tsee ev$) the body in an alist binding the formals.  But
  @('ev$') insists that the expression object being evaluated be @(see tame) or
  else assigns it a default value.  This insistence on tameness is due to
  fundamental logical reasons; otherwise, @('apply$') would allow us to prove
  @('NIL').  So axiomatically @('apply$') operates as ``naively expected'' only
  on @('tamep-lambdap') objects.  One consequence of this, which we expect will
  be a minor inconvenience, is that unlike ACL2's lambda expressions
  @('apply$')'s @('LAMBDA') objects, when used in definitions of new functions,
  may not include recursive calls of the function being defined because they
  fail the tameness test.</p>

  <p>But wait!  There's more.  Execution efficiency of @('apply$') imposes some
  non-logical restrictions.  These restrictions come from ACL2's execution
  story with respect to Common Lisp, and from the Common Lisp compiler.  To
  execute @('LAMBDA') objects most efficiently they must be well-formed, which
  is a concept even stronger than tameness.  Among other requirements,
  well-formed @('LAMBDA') objects obey the ACL2 and Common Lisp rules on
  variable names (not every symbol is a legal variable), on the use of free
  variables, on the body being a fully translated formal term, that the
  declarations, if any, be meaningful to the Common Lisp compiler, etc.  You
  can read about well-formedness in @(tsee well-formed-lambda-objectp) if you
  want, but we don't encourage beginners to go there!</p>

  <p>Note: Even well-formedness is not enough to guarantee execution of
  compiled code.  The @('LAMBDA') object must also be guard verified (see
  @(tsee verify-guards) for a discussion) and its guard must be satisfied by
  the arguments to which it is applied.</p>

  <p>Note: A peculiar aspect of @('LAMBDA') objects is that they can be written
  as legal ACL2 constants <i>before</i> they are well-formed @('LAMBDA')
  objects, e.g., by referring to undefined functions, @(':program') mode
  functions, unbadged functions, etc.  They are, after all, just arbitrary
  quoted objects and any value in ACL2 can be quoted.  An ill-formed
  @('LAMBDA') object can <i>become</i> well-formed if the world is
  appropriately extended, e.g., the appropriate @('defun')s or
  @('defwarrant')s are made.  Perhaps worse, they can be well-formed and then
  <i>become</i> ill-formed by an undo.  So at runtime @('apply$') has to check
  that the function symbol or @('LAMBDA') object is appropriate.  There is a
  sophisticated cache behind the execution machinery for @('LAMBDA') objects in
  the evaluation theory.  See @(tsee print-cl-cache).</p>

  <h3>About Lambda$ Expressions</h3>

  <p>Rather than force users to type well-formed @('LAMBDA') objects as quoted
  constants, ACL2 provides a macro allowing you to enter @('LAMBDA') objects by
  typing something that looks like a lambda expression but which is properly
  translated and generates well-formed results (or causes a translation
  error).</p>

  <p>That macro -- which is not really a defined macro but is built into ACL2's
  translation mechanism -- is called @(tsee lambda$) and uses of it in terms
  are called ``@('lambda$') expressions.''  @('Lambda$') expressions may only be
  used in argument slots of @(see ilk) @(':FN').</p>

  <p>An example of a @('lambda$') expression is the first argument of
  @('collect$') in</p>

  @({
  (collect$ (lambda$ (x) (+ 1 x)) lst)
  })

  <p>That @('lambda$') expression essentially translates to the quoted
  well-formed @('LAMBDA') object</p>

  @({
  '(LAMBDA (X) (BINARY-+ '1 X))
  })

  <p>Note that the body is fully translated, unlike its appearance in the
  @('lambda$') expression.  We say ``essentially'' because @('lambda$') always
  add a @('(DECLARE (IGNORABLE v1 ... vn))') that includes every formal.  In
  addition, except when translating in theorems, @('lambda$') tags the
  translated body with a @(tsee RETURN-LAST) expression to indicate it came
  from a @('lambda$').  Despite these differences, the meaning of the
  translated @('lambda$') is the simple quoted @('LAMBDA') object shown.</p>

  <p>@('Lambda$') expressions never appear in a fully translated term.  All the
  @('lambda$') objects will have been translated into quoted @('LAMBDA')
  objects.</p>

  <p>The body of a @('lambda$') expression must return a single value that is
  neither a @(see stobj) nor a @(see df).  The following example illustrates
  this point.</p>

  @({
  (defun$ f1 (x)
    (declare (xargs :guard t))
    (mv x x))

  ; ERROR!  The body of the lambda$ returns two values.
  (defun f2 (y)
    (declare (xargs :guard t))
    (apply$ (lambda$ (x) (f1 x))
            (list y)))

  ; Succeeds.
  (defun f2 (y) (declare (xargs :guard t))
    (apply$ '(lambda (x) (f1 x))
            (list y)))
  })

  <p>Finally, to see how a @('lambda$') expression translates, see @(tsee
  translam).</p>")

(defxdoc lambda$
  :parents (apply$)
  :short "Lambda object constructor for use with @('apply$')"
  :long "<p>@('Lambda$') is a built-in ACL2 ``macro'' that allows you to enter
  well-formed fully-translated quoted @('LAMBDA') objects in argument positions
  of ilk @(':FN').  We urge you to use @('lambda$') instead of trying to type
  quoted @('LAMBDA') objects meant for use by @('apply$').  We explain and
  document @('lambda$') below.</p>

  <p>Intuitively, a quoted @('LAMBDA') object is a quoted constant like</p>

  @({
  '(LAMBDA (X) (BINARY-+ '1 X))
  })

  <p>e.g., a quoted constant beginning with the symbol @('LAMBDA') and listing
  some formal variables, possibly some declarations, and a fully translated
  body satisfying various rules.  @(tsee Apply$) can handle quoted @('LAMBDA')
  objects provided they have the right basic shape and all the listed formals
  are symbols and the bodies are @(see tame).  But it is difficult to type
  fully translated bodies and, for runtime efficiency, it is important that the
  quoted @('LAMBDA') objects satisfy additional (logically unnecessary)
  well-formedness restrictions allowing faster guard checking and
  compilation.</p>

  <p>One should strive to always enter ``well-formed @('LAMBDA') objects.''
  The details of well-formedness may be found in @(tsee
  well-formed-lambda-objectp) but our hope is that mastering those details is
  unnecessary because ACL2 provides a built-in ``macro,'' @('lambda$'), for
  constructing quoted well-formed @('LAMBDA') objects.  We urge you to use
  @('lambda$') instead of typing quoted @('LAMBDA') objects!  That is, write
  @('(lambda$ (x) (+ 1 x))') instead of @(''(LAMBDA (X) (BINARY-+ '1 X))').</p>

  <p>@('Lambda$') <i>terms may only appear in argument slots of ilk</i>
  @(':FN')!</p>

  <code>
  Examples:
  (lambda$ (x y) (append x (list y)))

  (lambda$ (n lst str)
           (declare (type integer n)
                    (type string str)
                    (xargs :guard (and (posp n)
                                       (true-listp lst)
                                       (&lt; (- n 1) (length lst)))))
           (nth (- n 1) lst))

  General Form:
  (lambda$ vars dcl* body)
  </code>

  <p>where the @('lambda$') expression occurs in an argument position of ilk
  @(':FN'), @('vars') is a list of distinct variable names, @('dcl*') is zero
  or more @('DECLARE') forms as described below, and @('body') is a term
  returning the appropriate number of values, which is currently always 1
  except when used in the translation of an expression of the form @('(loop$
  ... DO ...)').  @('Body') must satisfy the same restrictions one would expect
  in a non-recursive @(tsee defun) event with the same formals, declarations
  and body.  In particular, @('body') should contain no free variables other
  than those listed in @('vars').  @('Lambda$') always adds a declaration that
  every formal is ignorable and, hence, we prohibit you from adding @('ignore')
  or @('ignorable') declarations in the @('lambda$') expression itself.
  @('Lambda$') expands to a well-formed quoted @('LAMBDA') object or else
  causes a translate-time error.</p>

  <p>The allowed @('DECLARE') forms in @('lambda$') are @('type') and
  @('xargs').  Furthermore, the only @(tsee xargs) keywords allowed are
  @(':guard') and @(':split-types').  The other @('XARGS') keywords, such as
  @(':measure'), @(':hints') or @(':guard-hints'), play no role.</p>

  <h3>About @('Lambda$')s and Prover Output</h3>

  <p>The translated form of a @('lambda$') expression is a quoted @(tsee
  lambda) object.  For example, @('(collect$ (lambda$ (x) (+ 1 x)) lst)')
  translates to</p>

  @({
  (COLLECT$ '(LAMBDA (X)
                   (DECLARE (IGNORABLE X))
                   (RETURN-LAST 'PROGN
                                '(LAMBDA$ (X) (+ 1 X))
                                (BINARY-+ '1 X)))
            LST)
  })

  <p>The @('lambda$') has been replaced by a quoted @('lambda').</p>

  <p>The prover tries to print each quoted @('lambda') object (that occurs
  an argument position of @(see ilk) :@('FN')) as a @('lambda$')
  expression that is (provably) functionally equal (see @(tsee fn-equal)) to
  the original @('lambda') object assuming the necessary warrants.  If the
  quoted @('lambda') object was produced by the expansion of a @('lambda$')
  expression and has not been simplified by subsequent rewriting, it will print
  as the original @('lambda$') expression.  This can be unfortunate if the
  original @('lambda$') expression was itself produced by a macro and contains
  logically irrelevant (but operationally important) tags.  This phenomenon
  occurs most often when @(tsee do-loop$)s are involved.</p>

  <p>Furthermore, since you are allowed to type in quoted @('lambda') objects
  directly, you may &mdash; or may not &mdash; see them printed by the prover
  as @('lambda$') expressions, depending on whether a suitable @('lambda$') is
  found.  If a quoted @('lambda') object contains a reference to a function
  symbol for which no @(tsee warrant) has been issued there is probably no
  provably equivalent @('lambda$').</p>

  <p>The main lessons here are</p>

  <ul>

  <li>you should use @('lambda$') rather than quoted @('lambda') objects in
  your prover input,</li>

  <li>you should make sure to warrant every user-defined function in your
  @('lambda$') expressions, and</li>

  <li>if you see a quoted @('lambda') object rather than a @('lambda$')
  expression in your prover output, that quoted @('lambda') object probably
  involves unwarranted symbols which will make it impossible to prove anything
  interesting about it.</li>

  </ul>

  <p>If you do not want the prover output to give special treatment to quoted
  @('lambda') objects in :@('FN') slots, do</p>

  @({
  (defattach-system (untranslate-lambda-object-p
                    constant-nil-function-arity-0))
  })

  <p>With this attachment, the prover will print all quoted @('lambda') objects
  as it would any other quoted constant.  You will see what is actually there.
  One drawback is that the resulting formulas cannot always be read back in
  and translated because of a prohibition on ``counterfeiting'' expansions of
  @('lambda$').  See @(see gratuitous-lambda-object-restrictions).</p>

  <h3>About Guard Verification of Lambda Objects</h3>

  <p>Quoted @('LAMBDA') objects, whether produced by hand (don't!) or by
  @('lambda$') may have guards.  If the @('LAMBDA') object is well-formed its
  guard plays the same role the guard of a defined function symbol plays when
  the object is @('apply$')d.  If the guard can be verified to imply the guards
  of the body (which we call <i>guard verification</i>), and if the guard holds
  of the actuals to which the object is applied (which we call <i>guard
  checking</i>), a compiled version of the object is run.  Otherwise, depending
  on how @(tsee set-guard-checking) has been configured, either an error is
  signaled or the object is interpreted under the axioms defining @('apply$')
  and @('ev$').  @('Apply$') caches its investigations into guard
  verification (but not guard checking) and compilation.  We discuss the cache
  in @(tsee print-cl-cache).</p>

  <p>When a guarded quoted @('LAMBDA') object is used in a @(':FN') slot of a
  function definition, its guards are verified as part of the guard
  verification step of @('defun') or @('verify-guards').  If that guard
  verification fails, checkpoints will be printed and you can use
  @(':guard-hints') or @(':hints') in the @('defun') or @('verify-guards')
  events to supply the necessary guidance.  When successful, the guard verified
  @('LAMBDA') objects in the @('defun') are recorded in the cache.</p>

  <p>But unlike defined function symbols, whose guards may be verified at
  @('defun')-time or at @('verify-guards')-time, quoted @('LAMBDA') expressions
  may be introduced without an associated event.  For example, the user may
  simply type</p>

  <code>
  ACL2 !&gt;(apply$ (lambda$ (x)
                          (declare (type (satisfies natp) x))
                          (* x x))
                 '(5))
  </code>

  <p>giving @('apply$') a @('LAMBDA') object never before seen.</p>

  <p>So @('apply$') must be ready to verify the guards of a quoted @('LAMBDA')
  object before attempting to apply it.  This is in contrast to what happens
  when @('apply$') is given a quoted function symbol.  (@('Apply$') can just
  look up whether a function symbol has been guard verified.)</p>

  <p>To try to verify the guards of a quoted @('LAMBDA') expression, @('apply$')
  limits itself to tau reasoning (see @(see introduction-to-the-tau-system)).  The
  idea is not to spend too much time making the decision as to whether compiled code
  can be used or not.  In addition, we don't want top-level evaluation, as shown
  in the user type-in above, to provoke full-blown theorem proving.</p>

  <p>Interpreting small quoted @('LAMBDA') objects can be done relatively
  quickly.  After all, when the interpreter reaches a guard verified function
  symbol inside the @('LAMBDA') body it runs compiled code.  It's only the body
  itself that is interpreted.</p>

  <p>But the tau system is pretty weak and so will be unable to verify some
  non-trivial guard conjectures, which will mean the @('LAMBDA') object is
  interpreted.  If the @('LAMBDA') object is very large or is being being used
  often, e.g., to map over a large object and check some property, you might
  really want to invest the time to verify its guards.  This can be done with
  @(tsee verify-guards), which as of Version 8.1 takes @('LAMBDA') objects and
  @('lambda$') terms and updates the cache.  E.g.,</p>

  @({
  (verify-guards
    (lambda$ (x)
             (declare (type (satisfies natp) x))
             (* x x)))
  })

  <p>While this functionality is available to you, deciding that you need to
  use it is problematic.  @('Apply$') prints no warning that it has failed to
  verify the guards of a @('LAMBDA') object and is running interpreted code.
  However, the utility @(tsee print-cl-cache) provides basic information about
  the cache and its documentation may help you discover which @('LAMBDA')
  objects in use are unverified.</p>")

(defxdoc last
  :parents (lists acl2-built-ins)
  :short "The last @(tsee cons) (not element) of a list"
  :long "<p>@('(Last l)') is the last @(tsee cons) of a list, @('l').  Here are
 examples.</p>

 @({
  ACL2 !>(last '(a b . c))
  (B . C)
  ACL2 !>(last '(a b c))
  (C)
 })

 <p>@('(Last l)') has a @(see guard) of @('(listp l)'); thus, @('l') need not
 be a @(tsee true-listp).</p>

 <p>@('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').</p>

 @(def last)")

(defxdoc last-cdr
  :parents (lists acl2-built-ins)
  :short "The last @(tsee cdr) of a list"
  :long "<p>@('(Last-cdr x)') is @('x') if @('x') is an @(tsee atom), and
 otherwise is the last @(tsee cdr) of a list.  Here are examples.</p>

 @({
  ACL2 !>(last-cdr '(a b . c))
  C
  ACL2 !>(last-cdr '(a b c))
  NIL
 })

 <p>@('(Last-cdr x)') has a @(see guard) of @('t').</p>

 @(def last-cdr)")

(defxdoc last-prover-steps
  :parents (set-prover-step-limit with-prover-step-limit
    programming-with-state
    acl2-built-ins)
  :short "The number of prover steps most recently taken"
  :long "<p>For discussions of prover step limits, See @(see
 set-prover-step-limit) and see @(see with-prover-step-limit).</p>

 <p>The @(see summary) printed for an @(see event) typically includes a line
 showing the prover steps counted, for example as follows.</p>

 @({
 Prover steps counted:  7240
 })

 <p>The value of the form @('(last-prover-steps state)') indicates the number
 of prover steps taken, in the sense described below, for the most recent
 context in which an event @(see summary) would normally be printed.  Note that
 the value of @('(last-prover-steps state)') is updated for all @(see events),
 and more generally, for all forms that are set up to print a @(see summary),
 such as calls of @(tsee thm) or @(tsee certify-book) &mdash; regardless of
 whether or not summary output is inhibited (see @(see set-inhibit-output-lst)
 and see @(see set-inhibited-summary-types)).  In particular, the value is
 updated (typically to @('nil')) for @(tsee table) @(see events), even when no
 summary is printed; for example, the value is updated to @('nil') for
 @('table') events such as @('(')@(tsee logic)@(')'), @('(')@(tsee
 program)@(')'), and even calls of @(tsee set-prover-step-limit).</p>

 <p>The value of @('(last-prover-steps state)') is determined as follows, based
 on the most recent summary context (as described above):</p>

 <blockquote>

 <p>@('nil'), if no prover steps were taken, e.g., with @('(thm (equal x x))');
 else,</p>

 <p>the (positive) number of steps taken, if the number of steps did not exceed
 the starting limit; else,</p>

 <p>the negative of the starting limit.</p></blockquote>

 <p>Note that the ``most recently completed event'' in this sense includes
 compound events.  Consider the following example.</p>

 @({
 (progn (thm (equal (append (append x y) z) (append x y z)))
        (thm (equal (car (cons x y)) x)))
 })

 <p>The summaries show (in some ACL2 versions, at least) 435 steps for the
 first call of @('thm') and 7 steps for the second call of @('thm'), with 442
 steps thus shown in the summary for the entire @('progn') call.  Subsequent
 evaluation of @('(last-prover-steps state)') returns 442.  On the other hand,
 suppose that @('(set-prover-step-limit 440)') is evaluated immediately before
 evaluating the @('progn') call above.  Then the summaries show the following
 for the two @('thm') calls and the @('progn') call, in order as follows.</p>

 @({
 Prover steps counted:  435
 Prover steps counted:  More than 5
 Prover steps counted:  More than 440
 })

 <p>Since the most recently completed event is the @('progn') call, then
 @('(last-prover-steps state)') returns -440.</p>

 <p>We conclude with two remarks for advanced users who wish to invoke
 @('last-prover-steps') in the development of utilities that track prover
 steps.</p>

 <p>Remark 1.  Suppose that you want to write a utility that takes some action
 based on the number of prover steps performed by the first event that is
 generated within a sequence of events, for example the number of prover steps
 taken to admit @('f1') in the following example.</p>

 @({
  (progn (defun f1 ...)
         (defun f2 ...))
 })

 <p>A solution is to record the steps taken by the first @(tsee defun) before
 executing subsequent events, as follows (see @(see make-event)).</p>

 @({
  (progn (defun f1 ...)
         (make-event (pprogn (f-put-global 'my-step-count
                                           (last-prover-steps state)
                                           state)
                             (value '(value-triple nil))))
         (defun f2 ...))
 })

 <p>Remark 2.  It is possible to write utilities that are treated as @(see
 events) for purposes of the discussion above; that is, their calls can be
 followed by evaluating @('(last-prover-steps state)') as described above.  For
 an example of how to do this using the ACL2 system macro
 @('with-ctx-summarized'), see the implementation of @(tsee prove$) in @(see
 community-book) @('books/tools/prove-dollar.lisp').</p>")

(defxdoc ld
  :parents (miscellaneous)
  :short "The ACL2 read-eval-print loop, file loader, and @(see command) processor"
  :long "<code>
 Examples:
 (LD "foo.lisp")              ; read and evaluate each form in file
                              ; "foo.lisp", in order
 (LD "foo.lisp" :ld-pre-eval-print t)
                              ; as above, but print each form to standard
                              ; character output just before it is evaluated

 General Form:
 (LD standard-oi                  ; open obj in channel, stringp file name
                                  ; to open and close, or list of forms
                                  ; Optional keyword arguments:
     :dir                ...      ; directory spec if standard-oi is a string
     :standard-co        ...      ; open char out or file to open and close
     :proofs-co          ...      ; open char out or file to open and close
     :current-package    ...      ; known package name
     :useless-runes      ...      ; :write/:read/:read?/n/-n/nil
                                  ;   (-100 &lt; n &lt; 0 or 0 &lt; n &lt;= 100)
                                  ;   (see @(see useless-runes))
     :ld-skip-proofsp    ...      ; nil, 'include-book, or t
                                  ;   (see @(see ld-skip-proofsp))
     :ld-redefinition-action ...  ; nil or '(:a . :b)
     :ld-prompt          ...      ; nil, t, or some prompt printer fn
     :ld-missing-input-ok ...     ; nil, t, :warn, or warning message
     :ld-pre-eval-filter ...      ; :all, :query, or some new name
     :ld-pre-eval-print  ...      ; nil, t, or :never
     :ld-post-eval-print ...      ; nil, t, or :command-conventions
     :ld-evisc-tuple     ...      ; nil or '(alist nil nil level length)
     :ld-error-triples   ...      ; nil or t
     :ld-error-action    ...      ; :return!, :return, :continue, :error,
                                  ;   or (:exit N)
     :ld-query-control-alist ...  ; alist supplying default responses
     :ld-verbose         ...)     ; nil or t
     :ld-always-skip-top-level-locals      ; nil or t
     :ld-user-stobjs-modified-warning ...) ; nil, t, or :same

 </code>

 <p>@('Ld') is the top-level ACL2 read-eval-print loop.  (When you call @(tsee
 lp), a little initialization is done in raw Common Lisp and then @('ld') is
 called.)  @('Ld') is also a general-purpose ACL2 file loader and a @(see
 command) interpreter.  @('Ld') is actually a macro that expands to a function
 call involving @(tsee state).  @('Ld') returns an ``error triple'' @('(mv erp
 val state)') as explained below.  (For much more on error triples, see @(see
 programming-with-state).)</p>

 <p>See @(see rebuild) for a variant of @('ld') that skips proofs.  See @(see
 output-to-file) for examples showing how to redirect output to a file.</p>

 <p>The arguments to @('ld'), except for @(':dir'), all happen to be global
 variables in @(tsee state) (see @(see state) and see @(see
 programming-with-state)).  For example, @(''')@(tsee current-package) and
 @(''')@(tsee ld-verbose) are global variables, which may be accessed via @('(@
 current-package)') and @('(@ ld-verbose)').  When @('ld') is called, it
 ``binds'' these variables.  By ``binds'' we actually mean the variables are
 globally set but restored to their old values on exit.  Because @('ld')
 provides the illusion of @(see state) global variables being bound, they are
 generally called ``@('ld') specials'' (after the Lisp convention of calling a
 variable ``special'' if it is referenced freely after having been bound).  (We
 say ``generally'' because technically, @('current-package') and
 @('useless-runes') are not considered to be @('ld') specials.)</p>

 <p>Note that all arguments but the first are passed via keyword.  Any variable
 not explicitly given a value in a call retains its pre-call value, with the
 exception of @(':')@(tsee ld-error-action), which generally defaults to
 @(':return!') if not explicitly specified.</p>

 <p>Just as an example to drive the point home: If @(tsee current-package) is
 @('"ACL2"') and you typed</p>

 @({
  (ld *standard-oi* :current-package "MY-PKG")
 })

 <p>you would find yourself in (an inner) read-eval-print loop in which the
 @(see current-package) was @('"MY-PKG"').  You could operate there as long
 as you wished, changing the current package at will.  But when you typed
 @(':')@(tsee q) you would return to the outer read-eval-print loop where the
 current package would still be @('"ACL2"').</p>

 <p>Roughly speaking, @('ld') repeatedly reads a form from @(tsee standard-oi),
 evaluates it, and prints its result to @(tsee standard-co).  It does this
 until the form is @(':')@(tsee q) or evaluates to an error triple whose value
 component is @(':')@(tsee q), or until the input channel or list is emptied.
 However, @('ld') has many bells and whistles controlled by the @('ld')
 specials.  Each such special is documented individually.  For example, see the
 documentation for @(tsee standard-oi), @(tsee current-package), @(see
 useless-runes), @(tsee ld-pre-eval-print), etc.</p>

 <p>A more precise description of @('ld') is as follows.  In the description
 below we use the @('ld') specials as variables, e.g., we say ``a form is read
 from @(tsee standard-oi).''  By this usage we refer to the current value of
 the named @(see state) global variable, e.g., we mean ``a form is read from
 the current value of @(''')@(tsee standard-oi).'' This technicality has an
 important implication: If while interacting with @('ld') you change the value
 of one of the @('ld') specials, e.g., @(''')@(tsee standard-oi), you will
 change the behavior of @('ld'), e.g., subsequent input will be taken from the
 new value.</p>

 <p>Three @('ld') specials are treated as channels: @(tsee standard-oi) is
 treated as an object input channel and is the source of forms evaluated by
 @('ld'); @(tsee standard-co) and @(tsee proofs-co) are treated as character
 output channels and various flavors of output are printed to them.  However,
 the supplied values of these specials need not actually be channels; several
 special cases are recognized.</p>

 <p>If the supplied value of one of these is in fact an open channel of the
 appropriate type, that channel is used and is not closed by @('ld').  If the
 supplied value of one of these specials is a string, the string is treated as
 a file name in (essentially) Unix syntax (see @(see pathname)) and a channel
 of the appropriate type is opened to/from that file.  Any channel opened by
 @('ld') during the binding of the @('ld') specials is automatically closed by
 @('ld') upon termination.  If @(tsee standard-co) and @(tsee proofs-co) are
 strings that represent the same file, only one channel to that file is opened
 and is used for both.</p>

 <p>As a special convenience, when @(tsee standard-oi) is a string and the
 @(':dir') argument is provided and not @('nil'), we look up @(':dir') just as
 is done for @(tsee include-book); also see @(tsee add-include-book-dir),
 @(tsee add-include-book-dir!), and @(tsee project-dir-alist).  Thus a suitable
 directory is prepended to create the filename.  Note that @('standard-oi')
 must be a string that is a relative pathname, not an absolute pathname.  For
 example, one can write @('(ld "arithmetic/top-with-meta.lisp" :dir
 :system)') to @('ld') that particular @(see community-books) library.  (Of
 course, for certified @(see books) you should almost always use @(tsee
 include-book) instead of @('ld').)  If @(':dir') is not specified, then a
 relative pathname is resolved using the connected book directory; see @(see
 cbd).  If you want to load a list of forms, then consider prepending a call of
 @(tsee set-cbd) to that list rather than using @(':dir'), which is not
 supported when @('standard-oi') is a list.</p>

 <p>Several other alternatives are allowed for @(tsee standard-oi).  If @(tsee
 standard-oi) is a true list then it is taken as the list of forms to be
 processed.  If @(tsee standard-oi) is a list ending in an open channel, then
 @('ld') processes the forms in the list and then reads and processes the forms
 from the channel.  Analogously, if @(tsee standard-oi) is a list ending a
 string, an object input channel from the named file is opened and @('ld')
 processes the forms in the list followed by the forms in the file.  That
 channel is closed upon termination of @('ld').</p>

 <p>In the cases that a string is to be converted to an object input channel
 &mdash; that is, when @(tsee standard-oi) is a string or is a list ending in a
 string &mdash; an error occurs by default if the conversion fails, presumably
 because the file named by the string does not exist.  However, if keyword
 argument @(':ld-missing-input-ok') is @('t'), then @('ld') immediately returns
 without error in this case, but without reading or executing any forms, as
 though @('standard-oi') is @('nil') and keyword arguments @(':ld-verbose') and
 @(':ld-prompt') both have value @('nil').  The other legal values for
 @(':ld-missing-input-ok') are @('nil'), which gives the default behavior, and
 @(':warn'), which behaves the same as @('t') except that a warning is printed,
 which contains the same information as would be printed for the default error
 described above.</p>

 <p>The remaining @('ld') specials are handled more simply and generally have
 to be bound to one of a finite number of tokens described in the @(':')@(tsee
 doc) entries for each @('ld') special.  Should any @('ld') special be supplied
 an inappropriate value, an error message is printed.</p>

 <p>Next, if @(tsee ld-verbose) is @('t'), @('ld') prints the message ``ACL2
 loading name'' where @('name') names the file or channel from which forms are
 being read.  At the conclusion of @('ld'), it will print ``Finished loading
 name'' if @(tsee ld-verbose) is @('t').</p>

 <p>One may generally omit @('ld-user-stobjs-modified-warning') except when
 calling @('ld') in the body of a definition.  In that case this keyword
 argument is required, and the value @('t') is recommended.  With that value, a
 warning will generally be printed if a user-defined @(see stobj) is modified
 by the call of @('ld'); value @('nil') avoids such warnings, and value
 @(':same') causes the value to be inherited from the existing value (generally
 from a superior call of @('ld')).  A discussion of these warnings is highly
 recommended reading before you give a value other than @('t'); see @(see
 user-stobjs-modified-warnings).</p>

 <p>Finally, @('ld') repeatedly executes the ACL2 read-eval-print step, which
 may be described as follows.  A @(see prompt) is printed to @(tsee
 standard-co) if @(tsee ld-prompt) is non-@('nil').  The format of the @(see
 prompt) is determined by @(tsee ld-prompt).  If it is @('t'), the default ACL2
 @(see prompt) is used.  If it is any other non-@('nil') value then it is
 treated as an ACL2 function that will print the desired @(see prompt).  See
 @(see ld-prompt).  In the exceptional case where @('ld')'s input is coming
 from the terminal @('(*standard-oi*)') but its output is going to a different
 sink (i.e., @(tsee standard-co) is not @(tsee *standard-co*)), we also print
 the @(see prompt) to the terminal.</p>

 <p>@('Ld') then reads a form from @(tsee standard-oi).  If the object read is
 a keyword, @('ld') constructs a ``keyword command form'' by possibly reading
 several more objects.  See @(see keyword-commands).  This construction process
 is sensitive to the value of @(tsee ld-keyword-aliases).  See @(see
 ld-keyword-aliases).  Otherwise, the object read is treated as the command
 form.</p>

 <p>(Technical Aside.  Some special handling takes place when @('ld') is called
 in the scope of @(tsee local), as in @('(local (ld <C>))') for a command,
 @('<C>').  In that case, after @('<C>') is evaluated, then if the result is an
 @(see error-triple) and @('<C>') is not already of the form @('(local <C0>)'),
 then when the command is stored in the ACL2 @(see world) it is stored as
 @('(local <C>)') instead of @('<C>').  See @(see ld-history) for a similar
 treatment of local commands.  End of Technical Aside.)</p>

 <p>@('Ld') next decides whether to evaluate or skip this form, depending on
 @(tsee ld-pre-eval-filter).  Initially, the filter must be either @(':all'),
 @(':query'), or a new name.  If it is @(':all'), it means all forms are
 evaluated.  If it is @(':query'), it means each form that is read is displayed
 and the user is queried.  Otherwise, the filter is a name and each form that
 is read is evaluated as long as the name remains new, but if the name is ever
 introduced then no more forms are read and @('ld') terminates.  See @(see
 ld-pre-eval-filter).</p>

 <p>If the form is to be evaluated, then @('ld') first prints the form to
 @(tsee standard-co), if @(tsee ld-pre-eval-print) is @('t').  With this
 feature, @('ld') can process an input file or form list and construct a script
 of the session that appears as though each form was typed in.  See @(see
 ld-pre-eval-print).</p>

 <p>@('Ld') then evaluates the form, with @(tsee state) bound to the current
 @(see state).  The result is some list of (multiple) values.  If a @(see
 state) is among the values, then @('ld') uses that @(see state) as the
 subsequent current @(see state).</p>

 <p>Depending on @(tsee ld-error-triples), @('ld') may interpret the result as
 an ``error.''  See @(see ld-error-triples).  We first discuss @('ld')'s
 behavior if no error signal is detected (either because none was sent or
 because @('ld') is ignoring them because @(tsee ld-error-triples) is
 @('nil')).</p>

 <p>In the case of a non-erroneous result, @('ld') does two things: First, if
 the logical @(see world) in the now current @(see state) is different than the
 @(see world) before execution of the form, @('ld') adds to the @(see world) a
 ``@(see command) landmark'' containing the form evaluated.  See @(see
 command-descriptor).  Second, @('ld') prints the result to @(tsee
 standard-co), but only if @(tsee ld-post-eval-print) is not @('nil').  The
 result is printed as a list of (multiple) values unless @(tsee
 ld-post-eval-print) is @(':command-conventions'), @(tsee ld-error-triples) is
 @('t'), and the result is an @(see error-triple), i.e., of the form @('(mv * *
 state)').  In that case, only the non-erroneous ``value'' component of the
 result is printed.  See @(see ld-post-eval-print).</p>

 <p>Whenever @('ld') prints anything (whether the input form, a query, or some
 results) it ``eviscerates'' it if @('ld-evisc-tuple') is non-@('nil').
 Essentially, evisceration is a generalization of Common Lisp's use of
 @('*print-level*') and @('*print-length*') to hide large substructures.  See
 @(see evisc-tuple) and also see @(see set-iprint).</p>

 <p>We now return to the case of a form whose evaluation signals an error.  In
 this case, @('ld') first restores the ACL2 logical @(see world) to what it was
 just before the erroneous form was evaluated.  Thus, a form that partially
 changes the @(see world) (i.e., begins to store properties) and then signals
 an error, has no effect on the @(see world).  You may see this happen on @(see
 command)s that execute several @(see events) (e.g., an @(tsee encapsulate) or
 a @(tsee progn) of several @(tsee defuns)): even though the output makes it
 appear that the initial @(see events) were executed, if an error is signaled
 by a later event the entire block of @(see events) is discarded.</p>

 <p>After rolling back, @('ld') takes an action determined by @(tsee
 ld-error-action).  If the action is @(':continue'), @('ld') merely iterates
 the read-eval-print step.  Note that nothing suggestive of the value of the
 ``erroneous'' form is printed.  If the action is @(':return'), @('ld')
 terminates normally; similarly if the action is @(':return!'), but a special
 value is returned that can cause superior @('ld') commands to terminate; see
 @(see ld-error-action) for details.  If the action is @(':error'), @('ld')
 terminates signaling an error to its caller.  If its caller is in fact
 another instance of @('ld') and that instance is watching out for error
 signals, the entire @(see world) created by the inner @('ld') will be
 discarded by the outer @('ld') if the inner @('ld') terminates with an
 error.  Note that if the action is @('(:exit N)'), then there is no rolling
 back, because ACL2 quits immediately with exit status @('N').</p>

 <p>@('Ld') returns an error triple, @('(mv erp val state)').  @('Erp') is
 @('t') or @('nil') indicating whether an error is being signaled.  If no error
 is signaled, @('val') is the ``reason'' @('ld') terminated and is one of
 @(':exit') (meaning @(':')@(tsee q) was read), @(':eof') (meaning the input
 source was exhausted), @(':error') (meaning an error occurred but has been
 suppressed), @(':filter') (meaning the @(tsee ld-pre-eval-filter) terminated
 @('ld')), @(':missing-input') (meaning that the specified input file is
 missing, in the case that keyword @(':ld-missing-input-ok') has a non-@('nil')
 value so that an error is avoided), or a cons pair whose first component is
 the symbol @(':STOP-LD'), which typically indicates that an error occurred
 while the value of variable @(''')@(tsee ld-error-action) was @(':RETURN!').
 See @(see ld-error-action) for details of this last case.</p>")

(defxdoc ld-always-skip-top-level-locals
  :parents (ld)
  :short "Determines whether @(tsee ld) skips @(tsee local) top-level forms"
  :long "<p>@('Ld-always-skip-top-level-locals') is an @(tsee ld) special (see
 @(see ld)).  The accessor is @('(ld-always-skip-top-level-locals state)') and
 the updater is @('(set-ld-always-skip-top-level-locals val state)').  The
 value of @('ld-always-skip-top-level-locals') must be either @('nil') or
 @('t').  The initial value of @('ld-always-skip-top-level-locals') is
 @('nil').</p>

 <p>The general-purpose ACL2 read-eval-print loop, @(tsee ld), is controlled by
 various flags that control its behavior, and
 @('ld-always-skip-top-level-locals') is one of them.  When the value is
 @('t'), @(tsee local) @(see events) are skipped when they are at the top level
 in the following sense: they are not evaluated in the scope of either a call
 of @(tsee certify-book), @(tsee include-book), or @(tsee encapsulate), or else
 during @(tsee make-event) expansion.</p>")

(defxdoc ld-error-action
  :parents (ld)
  :short "Determines @(tsee ld)'s response to an error"
  :long "<p>@('Ld-error-action') is an @(tsee ld) special (see @(see ld)).  The
 accessor is @('(ld-error-action state)') and the updater is
 @('(set-ld-error-action val state)').  @('Ld-error-action') must be
 @(':continue'), @(':return'), @(':return!'), @(':error'), or @('(:exit N)')
 for some natural number @('N').  The initial value of @('ld-error-action') is
 @(':continue'), which means that the top-level ACL2 @(see command) loop (see
 @(tsee lp)) will not exit when an error is caused by @('user-typein').  But
 the default value for @('ld-error-action') on calls of @(tsee ld) is
 @(':return!'), with one exception: in the case that the value of @(tsee ld)
 special @('ld-error-action') is @('(:exit N)'), the default remains that
 value.</p>

 <p>The general-purpose ACL2 read-eval-print loop, @(tsee ld), reads forms from
 @(tsee standard-oi), evaluates them and prints the result to @(tsee
 standard-co).  Note that the ACL2 top-level loop (see @(tsee lp)) results from
 an invocation of @(tsee ld).</p>

 <p>However, there are various flags that control @(tsee ld)'s behavior and
 @('ld-error-action') is one of them.  Suppose that @(tsee ld-error-triples) is
 @('t') and a form evaluates to an @(see error-triple) @('(mv erp val state)').
 If the ``error component'', @('erp'), is non-@('nil'), then an error is said
 to have occurred.  If an error occurs, @(tsee ld)'s action depends on
 @('ld-error-action').  If it is @(':continue'), @(tsee ld) just continues
 processing the forms in @(tsee standard-oi).  If it is @(':return') or
 @(':return!'), @(tsee ld) stops and returns as though it had emptied the
 channel.  If it is @(':error'), @(tsee ld) stops and returns, signaling an
 error to its caller by returning an error triple with non-@('nil') error
 component, and reverting the logical @(see world) to its value just before
 that call of @(tsee ld).  If it is @('(:exit N)'), then ACL2 quits with exit
 status @('N').  Later in this topic we discuss another case in which an error
 is said to have occurred: when the value component of an error triple is of
 the form @('(:STOP-LD . x)').</p>

 <p>To see this effect of @(':ERROR') for @('ld-error-action'), consider the
 following example.</p>

 @({
  (ld '((defun f (x) x) (defun bad (x)) (defun g (x) x)))
 })

 <p>When the @(tsee defun) of @('bad') fails (because its body is missing),
 evaluation of the @('ld') call stops; thus, the @(tsee defun) of @('g') is not
 evaluated.  The definition of @('f') will be removed from the logical @(see
 world) before the call of @('ld') returns.</p>

 <p>However, by default each user call of @('ld') is made with a
 @('ld-error-action') of @(':RETURN!') (not @(':ERROR')).  In the common case
 that all nested calls of @('ld') inside the ACL2 loop are made this way, an
 error will not roll back the logical @(see world).  However, it will still
 halt evaluation of forms for the current call of @('ld') and any parent calls
 of @('ld') (other than the call made on behalf of @('lp') that entered the
 ACL2 loop in the first place), as though there were no more forms to
 evaluate.</p>

 <p>We have already discussed the behavior of @('ld') when an error occurs.
 But there is another case when @('ld') can stop processing more forms: when
 @('ld-error-action') is not @(':CONTINUE'), @(tsee ld-error-triples) is
 @('t'), and evaluation of a form returns an error triple @('(mv nil val
 state)'), where @('nil') is the error component and whose ``value component'',
 @('val') is a @(tsee cons) pair whose @(tsee car) is the symbol @(':STOP-LD').
 Let @('val') be the pair @('(:STOP-LD . x)').  If @('ld-error-action') is of
 the form @('(:EXIT N)'), then ACL2 quits with exit status @('N').
 Otherwise (i.e., when @('ld-error-action') is @(':RETURN'), @(':RETURN!'), or
 @(':ERROR')), the call of @('ld') returns the error triple @('(mv
 nil (:STOP-LD n . x) state)'), where @('n') is the value of @(tsee state)
 global variable @(''ld-level') at the time of termination.  The following
 example illustrates how this works.</p>

 @({
  (ld '((defun f1 (x) x)
        (ld '((defun f2 (x) x)
              (mv nil '(:STOP-LD my-error more-info) state)
              (defun g2 (x) x)))
        (defun g1 (x) x)))
 })

 <p>The outer call of @('ld') returns the value</p>

 @({
  (:STOP-LD 2 3 MY-ERROR MORE-INFO)
 })

 <p>and leaves us in a world the includes definitions for @('f1') and @('f2'),
 but no definition for @('g1') or @('g2') since neither of their two @('defun')
 forms was evaluated.  The value of @(tsee state) global @(''ld-level') is
 incremented from 1 to 2 when the outer @('ld') is entered and then again to 3
 when the inner @('ld') is entered.  When the inner @('ld') encounters the
 error triple @('(mv nil (:STOP-LD my-error more-info) state)'), it sees
 @(':STOP-LD') in the @('car') of the value component and pushes the current
 value of @(''ld-level'), 3, onto the @(tsee cdr) of that value, to return the
 value triple @('(mv nil (:STOP-LD my-error 3 more-info) state)').  The outer
 of @('ld') then sees this value and returns @('(mv nil (:STOP-LD my-error 2 3
 more-info) state)'), since its current value of @(''ld-level') is 2 after the
 inner @('ld') exits.</p>

 <p>That concludes our discussion of how these special @(':STOP-LD') values are
 handled; but how are they created?  While they can be created directly by
 evaluation results as suggested in the example above, that is not the standard
 way.  Rather, @('ld') returns an error triple @('(mv nil (:STOP-LD n)
 state)'), where @('n') is the value of variable @('ld-level') at the time of
 termination, when the following conditions hold: an error occurs,
 @('ld-error-action') is @('RETURN!') (which is the default), and @(tsee
 ld-error-triples) is @('t') (the default).  The following example, which is a
 bit similar to the preceding one, illustrates both creation and handling of
 the special @(':STOP-LD') values.</p>

 @({
  (ld '((defun f1 (x) x)
        (ld '((defun f2 (x) x)
              (ld '((defun f3 (x) x)
                    (defun bad (x)) ; ERROR -- missing the body
                    (defun g3 (x) x)))
              (defun g2 (x) x)))
        (defun g1 (x) x)))
 })

 <p>The result is that @('f1'), @('f2'), and @('f3') are defined, but none of
 @('g1'), @('g2'), or @('g3') is defined.  Let's see why.  The innermost call
 of @(tsee ld) has a default @(':ld-error-action') of @(':RETURN!') (as do the
 other calls).  So when the definition of @('bad') fails, then the innermost
 @('ld') returns @('(mv nil (:STOP-LD 4) state)').  The middle @('ld') sees
 this value, and since its @(':ld-error-action') is not @(':CONTINUE') (because
 it has the default value of @(':RETURN!')), it returns before considering the
 definition of @('g2'), with value @('(mv nil (:STOP-LD 3 4) state)').  The
 topmost call of @('ld') similarly sees the @(':STOP-LD'); stops evaluation of
 forms, without defining @('g1'); and returns @('(mv nil (:STOP-LD 2 3 4)
 state)').</p>")

(defxdoc ld-error-triples
  :parents (ld)
  :short "Determines whether a form caused an error during @(tsee ld)"
  :long "<p>@('Ld-error-triples') is an @(tsee ld) special (see @(see ld)).
 The accessor is @('(ld-error-triples state)') and the updater is
 @('(set-ld-error-triples val state)').  @('Ld-error-triples') must be either
 @('t') or @('nil').  The initial value of @('ld-error-triples') is @('t').</p>

 <p>The general-purpose ACL2 read-eval-print loop, @(tsee ld), reads forms from
 @(tsee standard-oi), evaluates them and prints the result to @(tsee
 standard-co).  Note that the ACL2 top-level loop (see @(tsee lp)) results from
 an invocation of @(tsee ld).</p>

 <p>However, there are various flags that control @(tsee ld)'s behavior and
 @('ld-error-triples') is one of them.  If this variable has the value @('t')
 then when a form evaluates to an @(see error-triple) @('(mv erp val state)')
 such that @('erp') is non-@('nil'), then an error is deemed to have occurred.
 When an error occurs in evaluating a form, @(tsee ld) rolls back the ACL2
 @(see world) to the configuration it had at the conclusion of the last
 error-free form.  Then @(tsee ld) takes the action determined by @(tsee
 ld-error-action).</p>")

(defxdoc ld-evisc-tuple
  :parents (ld)
  :short "Determines whether @(tsee ld) suppresses details when printing"
  :long "<p>@('Ld-evisc-tuple') is an @(tsee ld) special (see @(see ld)).  The
 accessor is @('(ld-evisc-tuple state)') and an updater is
 @('(set-ld-evisc-tuple val state)'), although the use of @(tsee
 set-evisc-tuple) is preferred for updating.  @('Ld-evisc-tuple') must be
 either @('nil'), which is its initial value, or a legal evisc-tuple: see @(see
 set-evisc-tuple).</p>

 <p>The general-purpose ACL2 read-eval-print loop, @(tsee ld), reads forms from
 @(tsee standard-oi), evaluates them and prints the result to @(tsee
 standard-co).  Note that the ACL2 top-level loop (see @(tsee lp)) results from
 an invocation of @(tsee ld).</p>

 <p>However, there are various flags that control @(tsee ld)'s behavior and
 @('ld-evisc-tuple') is one of them.  @(tsee Ld) may print the forms it is
 evaluating and/or the results of evaluation.  Depending on the value of
 @('ld-evisc-tuple') @(tsee ld) may ``eviscerate'' objects before printing
 them.  See @(see set-evisc-tuple) for a discussion of evisceration and of how
 other evisc-tuples affect the printing of error messages and warnings, as well
 as other output not from @('ld').</p>")

(defxdoc ld-history
  :parents (ld history)
  :short "Saving and querying command history"
  :long "<p>See @(see ld) for background on the ACL2 read-eval-print loop.  The
 present topic pertains to a history kept for commands issued to that loop,
 which we call an ``ld-history'' (pronounced ``ell dee history'').  Here are
 some things to keep in mind when reading this topic.</p>

 <ul>

 <li>Each entry in the history includes the input command, the value returned,
 and other information, as explained further below.</li>

 <li>This is about commands, not events: that is, we are concerned with forms
 that are submitted for evaluation to the top-level loop.  See @(see
 command).</li>

 <li>An entry is saved for every command submitted by the user, even if it
 doesn't change the ACL2 @(see world) &mdash; e.g., @('(+ 3 4)') &mdash; and
 even if it undoes commands &mdash; e.g., @(':')@('ubt').</li>

 <li>Keyword commands are turned into s-expressions before saving an entry; see
 @(see keyword-commands).  For example, the input @(':ubt :x') is stored in an
 entry as the input @('(ubt ':x)').</li>

 <li>When an entry is saved for a command @('C') that is evaluated in the
 context of a call of @(tsee local), where @('C') evaluates to an @(see
 error-triple), then @('C') is stored in the entry as @('(local C)') unless
 @('C') is already a call of @('local').  (Technical Aside: This behavior
 supports local @(see portcullis) commands.)</li>

 <li>The ld-history saves entries not only for commands issued in the original
 top-level loop, but also for commands issued in (recursive) calls of @(tsee
 ld) &mdash; but not during @(tsee make-event) expansion.</li>

 <li>Entries are generally saved even when there are errors.  However, entries
 are not saved for commands that exit with raw Lisp errors.</li>

 </ul>

 <p>Also see @(see community-books) file @('books/demos/ld-history-input.lsp')
 for examples.  The output from calling @(tsee ld) on that file (by calling the
 @(tsee run-script) tool in @('books/demos/ld-history-book.acl2')) is in @(see
 community-books) file @('books/demos/ld-history-log.txt').</p>

 <p>The ld-history is a stack, represented as a list with the most recent
 commands at the front.  But by default ACL2 is in <i>single-entry mode</i>,
 where the list is kept at length 1: an entry is saved in the ld-history only
 for the most recent command, and the previous entry is discarded.  We now
 describe relevant utilities, including one that can switch to
 <i>multiple-entry mode</i>, where all entries are kept until a utility is
 called explicitly to discard old entries.  Note that the mode is determined by
 the length of the ld-history: single-entry mode when length 1, multiple-entry
 mode when length 2 or more.</p>

 <ul>

 <li>@('(ld-history state)')<br/>

 This utility returns a list of structures, denoted ``ld-history entries'',
 with the most recent one first.  By default, this list has length 1, but that
 can be changed; see @('adjust-ld-history') below.  Each entry in the list is
 recognized by the following predicate.  <b>NOTE</b>: This query is evaluated
 before the ld-history stored in the ACL2 state is updated with a new entry,
 based on the current command; so the previous command will be at the top of
 the returned stack, not the current command.  (In particular, submitting the
 form @('(ld-history state)') at the ACL2 prompt does not put that form at the
 front of the returned list.)</li>

 <li>@('(weak-ld-history-entry-p x)')<br/>

 This function returns @('t') if @('x') has the shape of an entry in the
 ld-history list, else @('nil').</li>

 <li>Here are accessors for an ld-history entry, which we think of as returning
 its fields.  The formal parameter @('entry') below is an entry in (i.e.,
 member of) @('(ld-history state)'); an example call is thus
 @('(ld-history-entry-input (car (ld-history state)))').<br/>

 <ul>

 <li>@('(ld-history-entry-input entry)')<br/>

 The user input</li>

 <li>@('(ld-history-entry-error-flg entry)')<br/>

 Non-@('nil') when there was an error translating the user input</li>

 <li>@('(ld-history-entry-stobjs-out/value entry)')<br/>

 When @('(ld-history-entry-error-flg entry)') is @('nil'), this is a cons whose
 @('car') is the @(see stobjs-out) &mdash; a list whose length is the number of
 values returned, with @('nil') in each position except when occupied by a
 symbol indicating a returned @(see stobj) for that position &mdash; and whose
 @('cdr') is the returned value in the single-value case, but is the list of
 returned values in the @(see multiple-value) case.</li>

 <li>@('(ld-history-entry-stobjs-out entry)')<br/>

 When @('(ld-history-entry-error-flg entry)') is @('nil'), this is the
 stobjs-out as described above; otherwise this is @('nil').</li>

 <li>@('(ld-history-entry-value entry)')<br/>

 When @('(ld-history-entry-error-flg entry)') is @('nil'), this is the value or
 values as described above; otherwise this is @('nil').</li>

 <li>@('(ld-history-entry-user-data entry)')<br/>

 This is @('nil') by default.  However, code can be provided to compute this
 field, as discussed below.</li>

 </ul></li>

 <li>@('(adjust-ld-history x state)')<br/>

 @('X') is @('t'), @('nil'), or an integer.  The result is an @(see
 error-triple) @('(mv nil value state)'), where @('value') and the effect are
 as follows, and where if there is no change (i.e., the effect is a no-op) then
 @('value') is @('(:no-change :length N)') where @('N') is the current length
 of the ld-history.

 <ul>

 <li>@('T'):<br/>

 Change to multiple-entry mode, where an entry is saved for every command, not
 just the most recent command.  There is no change if already in multiple-entry
 mode; otherwise the returned @('value') is @('(:saving-ld-history t)').</li>

 <li>@('NIL'):<br/>

 Change to single-entry mode, where an entry is saved only for the most recent
 command.  There is no change if already in single-entry mode; otherwise the
 returned @('value') is @('(:saving-ld-history nil)'), and all old entries will
 be discarded (to produce a single-element ld-history).</li>

 <li>Positive integer @('k'):<br/>

 Replace the current ld-history by its first @('k') entries, except there is no
 change if in single-entry mode or if @('k') is not less than the length of the
 current ld-history.  Note that by ``current ld-history'' we refer to the
 ld-history in effect at the time @('adjust-ld-history') is invoked, which does
 not include the current command being evaluated.  (Thus, even if @('k') is 1,
 multiple-entry mode will be preserved: the ld-history will have 2 entries
 immediately after the current command completes.)  The returned @('value') is
 @('(:ld-history-truncated :old-length LEN :new-length k)'), where @('LEN') is
 the length of the current ld-history before the change.</li>

 <li>Negative integer @('-k'):<br/>

 This is intended to specify removal of the oldest @('k') entries from the
 current ld-history.  Thus, it is treated identically to argument @('k2') where
 @('k2') is the sum of @('-k') and the length of the current ld-history, but
 only if that sum is positive; else there is no change.  For example, suppose
 that @('-k') is -3.  If the current ld-history, @('h'), has length 2 or 3,
 then there is no change; but if @('h') has length 10, then it is to be
 replaced by @('(take 7 h)') and the length will actually thus be 8 after the
 current command completes.</li>

 </ul>

 </li></ul>

 <p>Note that a call of @('adjust-ld-history') is not an @(see event) that can
 be placed directly in @(see books) or @(tsee encapsulate) forms.</p>

 <p>Remark.  If @('(adjust-ld-history n state)') is evaluated while in
 multiple-entry mode, where n is a positive integer less than the current
 length of the ld-history, then the new ld-history after returning to the
 prompt will have length @('n+1').  That's essentially because it will have
 length @('n') immediately after that call of @('adjust-ld-history') is
 evaluated, and then a new entry for the current command (which could be that
 call itself, if that's what was submitted at the prompt) will be pushed onto
 the ld-entry just before returning to the prompt.  We say ``essentially''
 because there is a Special Case: when @('n') is 1 then a 2-element list of
 entries @('(e1 e2)') is created where @('e2') has fields that are all
 @('nil'); then when the new entry @('e') is pushed onto the ld-history,
 @('e2') is dropped so that the new ld-history is @('(e e1)').  This
 special-case trick is also used in multiple-entry mode when @('n') is @('-k')
 where @('k') is one less than the length of the current ld-history, since that
 is treated the same as @('(adjust-ld-history 1 state)'); and this trick is
 also used when @('(adjust-ld-history t state)') switches from single-entry
 mode to multiple-entry mode.  End of Remark.</p>

 <p>Finally we discuss the user-data field of a ld-history entry, which (as
 noted above) has default @('nil').  It is accessed using
 @('(ld-history-entry-user-data entry)').  It is set automatically when
 the ld-history is extended with a new entry: the function call
 @('(set-ld-history-entry-user-data input error-flg stobjs-out/value state)'),
 is executed where the actuals are the other fields of the entry as indicated,
 e.g., the first actual is the input field of the new entry
 (as returned by the function, @('ld-history-entry-input')).  Although
 @('set-ld-history-entry-user-data') returns @('nil') by default, this can be
 changed by providing your own function with a @(':')@(tsee guard) of @('t')
 and the same formal parameters (which however may be renamed, other than
 @('state')).  To make that change, define a function, which here we call
 @('my-user-data'), and then attach it to @('set-ld-history-entry-user-data'),
 as follows.</p>

 @({
 (defun my-set-user-data (input error-flg stobjs-out/value state)
   (declare (xargs :guard t))
   ...)
 (defattach-system set-ld-history-entry-user-data my-set-user-data)
 })

 <p>The following example illustrates how to store the length of the ACL2 @(see
 world) in the user-data.  Note that the @(see world) present in the @(see
 state) at the time the user-data is set, computed as @('(w state)'), is almost
 the final world produced by the command &mdash; it is missing just one triple,
 a so-called command marker.</p>

 @({
 (defun my-world-length (input error-flg stobjs-out/value state)
   (declare (xargs :guard t :stobjs state)
            (ignore input error-flg stobjs-out/value))
   (len (w state)))

 (defattach-system set-ld-history-entry-user-data my-world-length)
 })

 <p>A subsequent inspection of the stored user-data shows the length of the
 current world, for example as follows.</p>

 @({
 ACL2 !>(ld-history-entry-user-data (car (ld-history state)))
 125914
 ACL2 !>
 })

 <p>Notice that we used @(tsee len), not @(tsee length), since the @(':')@(tsee
 guard) specified for our function needs to be @('t').  Alternative
 definitions, which however are less efficient, are as follows.</p>

 @({
 (defun my-world-length (input error-flg stobjs-out/value state)
   (declare (xargs :guard t :stobjs state)
            (ignore input error-flg stobjs-out/value))
   (and (true-listp (w state))
        (length (w state))))

 (defun my-world-length (input error-flg stobjs-out/value state)
   (declare (xargs :guard t :stobjs state)
            (ignore input error-flg stobjs-out/value))
   (ec-call (length (w state))))
 })

 <p>Here is how to restore the original behavior, i.e., the default where
 the user-data is set to @('nil').</p>

 @({
 (defattach-system set-ld-history-entry-user-data
                   set-ld-history-entry-user-data-default)
 })

")

(defxdoc ld-keyword-aliases
  :parents (ld)
  :short "Abbreviation of some keyword commands"
  :long "@({
  Examples:
  (set-ld-keyword-aliases '((:q 0 q-fn)
                            (:e 0 exit-acl2-macro))
                          state)
  (ld-keyword-aliases state) ; current value of the ld-keyword-aliases table
 })

 <p>@('Ld-keyword-aliases') is the name of a ACL2 table (see @(see table)) and
 also the name of a function of @('state') that returns the value of this
 table.  That value must be an alist, each element of which is of the form
 @('(:keyword n fn)'), where @(':keyword') is a keyword, @('n') is a
 nonnegative integer, and @('fn') is a function symbol of arity @('n'), a macro
 symbol, or a @('lambda') expression of arity @('n').  When @('keyword') is
 typed as an @(tsee ld) command, @('n') more forms are read, @('x1, ..., xn'),
 and the form @('(fn 'x1 ... 'xn)') is then evaluated.  The initial value of
 the @('ld-keyword-aliases') @(see table) is @('nil').</p>

 <p>ACL2 provides functions to modify the @('ld-keyword-aliases') table, as
 follows.</p>

 <blockquote>

 <p>@('(Set-ld-keyword-aliases val state)'): sets the table to @('val'), which
 must be a legal alist as described above.  This is an event that may go into a
 book (see @(see events)), but its effect will be @(see local) to that
 book.</p>

 <p>@('Set-ld-keyword-aliases!') is the same as @('set-ld-keyword-aliases'),
 except that its effect is not @(see local).  Indeed, the form
 @('(set-ld-keyword-aliases val state)') is equivalent to the form @('(local
 (set-ld-keyword-aliases! val state)').</p>

 <p>@('(Add-ld-keyword-alias key val state)'): modifies the table by binding
 the keyword @('key') to @('val'), which must be a legal value as described
 above.  This is an event that may go into a book (see @(see events)), but its
 effect will be @(see local) to that book.</p>

 <p>@('Add-ld-keyword-alias!') is the same as @('add-ld-keyword-alias'), except
 that its effect is not @(see local).  Indeed, the form
 @('(add-ld-keyword-alias key val state)') is equivalent to the form @('(local
 (add-ld-keyword-alias! key val state)').</p>

 </blockquote>

 <p>Consider the first example above:</p>

 @({
  (set-ld-keyword-aliases '((:q 0 q-fn)
                            (:e 0 exit-acl2-macro))
                          state)
 })

 <p>With this event, @(':')@(tsee q) is redefined to have the effect of
 executing @('(q-fn)'), so for example if you have defined @('q-fn') with</p>

 @({
  (defmacro q-fn ()
    '(er soft 'q "You un-bound :q and now we have a soft error."))
 })

 <p>then @(':')@(tsee q) will cause an error, and if you have defined</p>

 @({
  (defmacro exit-acl2-macro () '(exit-ld state))
 })

 <p>then @(':e') will cause the effect (it so happens) that @(':')@(tsee q)
 normally has.  If you prefer @(':e') to @(':')@(tsee q) for exiting the ACL2
 loop, you might even want to put such definitions of @('q-fn') and
 @('exit-acl2-macro') together with the @('set-ld-keyword-aliases') form above
 into your @('"acl2-customization.lsp"') file; see @(see
 acl2-customization).</p>

 <p>The general-purpose ACL2 read-eval-print loop, @(tsee ld), reads forms from
 @(tsee standard-oi), evaluates them and prints the result to @(tsee
 standard-co).  Note that the ACL2 top-level loop (see @(tsee lp)) results from
 an invocation of @(tsee ld).</p>

 <p>However, there are various flags that control @(tsee ld)'s behavior and
 @('ld-keyword-aliases') is one of them.  @('Ld-keyword-aliases') affects how
 keyword commands are parsed.  Generally speaking, @(tsee ld)'s command
 interpreter reads ``@(':fn x1 ... xn')'' as ``@('(fn 'x1 ... 'xn)')'' when
 @(':fn') is a keyword and @('fn') is the name of an @('n')-ary function; see
 @(see keyword-commands).  But this parse is overridden, as described above,
 for the keywords bound in the @('ld-keyword-aliases') @(see table).</p>")

(defxdoc ld-missing-input-ok
  :parents (ld)
  :short "Determine whether @(tsee ld) causes an error for a missing file"
  :long "<p>@('Ld-missing-input-ok') is an @(tsee ld) special (see @(see ld)).
 The accessor is @('(ld-missing-input-ok state)') and the updater is
 @('(set-ld-missing-input-ok val state)').  The value of
 @('ld-missing-input-ok') must be either @('nil'), @('t'), or @(':warn').  The
 initial value of @('ld-missing-input-ok') is @('nil').</p>

 <p>The general-purpose ACL2 read-eval-print loop, @(tsee ld), is controlled by
 various flags that control its behavior, and @('ld-missing-input-ok') is one
 of them.  In brief, the first argument of @('ld') can indicate a file from
 which to read input.  If the file does not exist, it is an error by default,
 but @('ld') becomes essentially a no-op if @('t') or @(':warn') is supplied
 for @(':ld-missing-input-ok'), where @(':warn') prints a warning.  Also see
 @(see ld).</p>")

(defxdoc ld-post-eval-print
  :parents (ld)
  :short "Determines whether and how @(tsee ld) prints the result of evaluation"
  :long "<p>@('Ld-post-eval-print') is an @(tsee ld) special (see @(see ld)).
 The accessor is @('(ld-post-eval-print state)') and the updater is
 @('(set-ld-post-eval-print val state)').  @('Ld-post-eval-print') must be
 either @('t'), @('nil'), or @(':command-conventions').  The initial value of
 @('ld-post-eval-print') is @(':command-conventions').</p>

 <p>The general-purpose ACL2 read-eval-print loop, @(tsee ld), reads forms from
 @(tsee standard-oi), evaluates them and prints the result to @(tsee
 standard-co).  Note that the ACL2 top-level loop (see @(tsee lp)) results from
 an invocation of @(tsee ld).</p>

 <p>However, there are various flags that control @(tsee ld)'s behavior and
 @('ld-post-eval-print') is one of them.  If this global variable is @('t'),
 @(tsee ld) prints the result.  In the case of a form that produces a multiple
 value, @(tsee ld) prints the list containing all the values (which, logically
 speaking, is what the form returned).  If @('ld-post-eval-print') is @('nil'),
 @(tsee ld) does not print the values.  This is most useful when @(tsee ld) is
 used to load a previously processed file.</p>

 <p>Finally, if @('ld-post-eval-print') is @(':command-conventions') and also
 @('ld-error-triples') is @('t'), then @(tsee ld) prints the result but treats
 ``error triples'' specially.  An ``error triple'' (see @(see error-triple))
 is a result, @('(mv erp val state)'), that consists of two ordinary values and
 @(tsee state).  Many ACL2 functions use such triples to signal errors.  The
 convention is that if @('erp') (the first value) is @('nil'), then the
 function is returning @('val') (the second value) as its conventional single
 result and possibly side-effecting @(see state) (as with some output).  If
 @('erp') is not @('nil'), then an error has been caused, @('val') is
 irrelevant and the error message has been printed in the returned @(see
 state).  Example ACL2 functions that follow this convention include @(tsee
 defun) and @(tsee in-package).  If such ``error producing'' functions are
 evaluated while @('ld-post-eval-print') is set to @('t'), then you would see
 them producing lists of length 3.  This is disconcerting to users accustomed
 to Common Lisp (where these functions produce single results but sometimes
 cause errors or side-effect @(see state)).  For more information about error
 triples, see @(see programming-with-state).</p>

 <p>When @('ld-post-eval-print') is @(':command-conventions') and a form
 produces an error triple @('(mv erp val state)') as its value, @(tsee ld)
 prints nothing if @('erp') is non-@('nil') and otherwise @(tsee ld) prints
 just @('val').  Because it is a misrepresentation to suggest that just one
 result was returned, @(tsee ld) prints the value of the global variable
 @(''triple-print-prefix') before printing @('val').  @(''triple-print-prefix')
 is initially @('" "'), which means that when non-erroneous error triples are
 being abbreviated to @('val'), @('val') appears one space off the left margin
 instead of on the margin.</p>

 <p>In addition, when @('ld-post-eval-print') is @(':command-conventions') and
 the value component of an error triple is the keyword @(':invisible') then
 @(tsee ld) prints nothing.  This is the way certain commands (e.g.,
 @(':')@(tsee pc)) appear to return no value.</p>

 <p>By printing nothing when an error has been signaled, @(tsee ld) makes it
 appear that the error (whose message has already appeared in @(see state)) has
 ``thrown'' the computation back to load without returning a value.  By
 printing just @('val') otherwise, we suppress the fact that @(see state) has
 possibly been changed.</p>")

(defxdoc ld-pre-eval-filter
  :parents (ld)
  :short "Determines which forms @(tsee ld) evaluates"
  :long "<p>@('Ld-pre-eval-filter') is an @(tsee ld) special (see @(see ld)).
 The accessor is @('(ld-pre-eval-filter state)') and the updater is
 @('(set-ld-pre-eval-filter val state)').  @('Ld-pre-eval-filter') must be
 either @(':all'), @(':query'), or a new name that could be defined (e.g., by
 @(tsee defun) or @(tsee defconst)).  (There is actually a value that may on
 rare occasions be set by the ACL2 system, @(':illegal-state'); we ignore that
 value here, but the curious reader is welcome to see @(see illegal-state).)
 The initial value of @('ld-pre-eval-filter') is @(':all').</p>

 <p>The general-purpose ACL2 read-eval-print loop, @(tsee ld), reads forms from
 @(tsee standard-oi), evaluates them and prints the result to @(tsee
 standard-co).  Note that the ACL2 top-level loop (see @(tsee lp)) results from
 an invocation of @(tsee ld).</p>

 <p>However, there are various flags that control @(tsee ld)'s behavior and
 @('ld-pre-eval-filter') is one of them.  If the filter is @(':all'), then
 every form read is evaluated.  If the filter is @(':query'), then after a form
 is read it is printed to @(tsee standard-co) and the user is asked if the form
 is to be evaluated or skipped.  If the filter is a new name, then all forms
 are evaluated until that name is introduced, at which time @(tsee ld)
 terminates normally.</p>

 <p>The @(':all') filter is, of course, the normal one.  @(':Query') is useful
 if you want to replay selected @(see command)s in some file.  The new name
 filter is used if you wish to replay all the @(see command)s in a file up
 through the introduction of the given one.</p>")

(defxdoc ld-pre-eval-print
  :parents (ld)
  :short "Determines whether @(tsee ld) prints the forms to be @('eval')'d"
  :long "<p>@('Ld-pre-eval-print') is an @(tsee ld) special (see @(see ld)).
 The accessor is @('(ld-pre-eval-print state)') and the updater is
 @('(set-ld-pre-eval-print val state)').  @('Ld-pre-eval-print') must be either
 @('t'), @('nil'), or @(':never').  The initial value of @('ld-pre-eval-print')
 is @('nil').</p>

 <p>The general-purpose ACL2 read-eval-print loop, @(tsee ld), reads forms from
 @(tsee standard-oi), evaluates them and prints the result to @(tsee
 standard-co).  Note that the ACL2 top-level loop (see @(tsee lp)) results from
 an invocation of @(tsee ld).</p>

 <p>However, there are various flags that control @(tsee ld)'s behavior and
 @('ld-pre-eval-print') is one of them.  If this global variable is @('t'),
 then before evaluating the form just read from @(tsee standard-oi), @(tsee ld)
 prints the form to @(tsee standard-co).  If the variable is @('nil'), no such
 printing occurs.  The @('t') option is useful if you are reading from a file
 of @(see command)s and wish to assemble a complete script of the session in
 @(tsee standard-co).</p>

 <p>The value @(':never') of @('ld-pre-eval-print') is rarely used.  During the
 evaluation of @(tsee encapsulate) and of @(tsee certify-book) forms,
 subsidiary events are normally printed, even if @('ld-pre-eval-print') is
 @('nil').  Thus for example, when the user submits an @(tsee encapsulate)
 form, all subsidiary events are generally printed even in the default
 situation where @('ld-pre-eval-print') is @('nil').  But occasionally one may
 want to suppress such printing.  In that case, @('ld-pre-eval-print') should
 be set to @(':never').  As described elsewhere (see @(see
 set-inhibit-output-lst)), another way to suppress such printing is to execute
 @('(set-inhibit-output-lst lst)') where @('lst') evaluates to a list including
 @(''prove') and @(''event').</p>")

(defxdoc ld-prompt
  :parents (ld)
  :short "Determines the @(see prompt) printed by @(tsee ld)"
  :long "<p>@('Ld-prompt') is an @(tsee ld) special (see @(see ld)).  The
 accessor is @('(ld-prompt state)') and the updater is @('(set-ld-prompt val
 state)').  @('Ld-prompt') must be either @('nil'), @('t'), or a function
 symbol that, when given an open output character channel and @(see state),
 prints the desired @(see prompt) to the channel and returns two values: the
 number of @(see characters) printed and the @(see state).  The initial value
 of @('ld-prompt') is @('t').</p>

 <p>The general-purpose ACL2 read-eval-print loop, @(tsee ld), reads forms from
 @(tsee standard-oi), evaluates them and prints the result to @(tsee
 standard-co).  Note that the ACL2 top-level loop (see @(tsee lp)) results from
 an invocation of @(tsee ld).</p>

 <p>However, there are various flags that control @(tsee ld)'s behavior and
 @('ld-prompt') is one of them.  @('Ld-prompt') determines whether @(tsee ld)
 prints a @(see prompt) before reading the next form from @(tsee standard-oi).
 If @('ld-prompt') is @('nil'), @(tsee ld) prints no @(see prompt).  If
 @('ld-prompt') is @('t'), the default @(see prompt) printer is used, which
 displays information that includes the current package, default @(see
 defun-mode), @(see guard) checking status (on or off), and @(tsee
 ld-skip-proofsp); see @(see default-print-prompt).</p>

 <p>If @('ld-prompt') is neither @('nil') nor @('t'), then it should be a
 function name, @('fn'), such that @('(fn channel state)') will print the
 desired @(see prompt) to @('channel') in @(tsee state) and return @('(mv col
 state)'), where @('col') is the number of @(see characters) output (on the
 last line output).  You may define your own @(see prompt) printing function,
 @('fn'), and install it with @('(set-ld-prompt 'fn state)').  However, a trust
 tag must be active (see @(see defttag)) when you set @('ld-prompt') to other
 than @('t') or @('nil') (with two exceptions: the functions @('brr-prompt')
 and @('wormhole-prompt'), which print the prompt in the @(see break-rewrite)
 loop and the general @(see wormhole) loop, respectively).</p>

 <p>If you supply an inappropriate @(see prompt) function, i.e., one that
 causes an error or does not return the correct number and type of results, the
 following odd @(see prompt) will be printed instead:</p>

 @({
  Bad Prompt
  See :DOC ld-prompt>
 })

 <p>which will lead you to this message.  You should either call @(tsee ld)
 appropriately next time or assign an appropriate value to
 @('ld-prompt').</p>")

(defxdoc ld-query-control-alist
  :parents (ld)
  :short "How to default answers to queries"
  :long "<p>@('Ld-query-control-alist') is an @(tsee ld) special (see @(see
 ld)).  The accessor is @('(ld-query-control-alist state)') and the updater is
 @('(set-ld-query-control-alist val state)').  Roughly speaking,
 @('ld-query-control-alist') is either @('nil') (meaning all queries should be
 interactive), @('t') (meaning all should default to the first accepted
 response), or an alist that pairs query ids to keyword responses.  The alist
 may end in either @('t') or @('nil'), indicating the default value for all ids
 not listed explicitly.  Formally, the @('ld-query-control-alist') must satisfy
 @('ld-query-control-alistp').  The initial @('ld-query-control-alist') is
 @('nil'), which means all queries are handled interactively.</p>

 <p>When an ACL2 query is raised, a unique identifying symbol is printed in
 parentheses after the word ``Query''.  This symbol, called the ``query id,''
 can be used in conjunction with @('ld-query-control-alist') to prevent the
 query from being handled interactively.  By ``handled interactively'' we mean
 that the query is printed to @(tsee *standard-co*) and a response is read from
 @(tsee *standard-oi*).  The alist can be used to obtain a ``default value''
 for each query id.  If this value is @('nil'), then the query is handled
 interactively.  In all other cases, the system handles the query without
 interaction (although text may be printed to @(tsee standard-co) to make it
 appear that an interaction has occurred; see below).  If the default value is
 @('t'), the system acts as though the user responded to the query by typing
 the first response listed among the acceptable responses.  If the default
 value is neither @('nil') nor @('t'), then it must be a keyword and one of the
 acceptable responses.  In that case, the system acts as though the user
 responded with the given keyword.</p>

 <p>Next, we discuss how the @('ld-query-control-alist') assigns a default
 value to each query id.  It assigns each id the first value paired with the id
 in the alist, or, if no such pair appears in the alist, it assigns the final
 @(tsee cdr) of the alist as the value.  Thus, @('nil') assigns all ids
 @('nil').  @('T') assigns all ids @('t').  @(''((:filter . nil) (:sysdef . :n)
 . t)') assigns @('nil') to the @(':filter') query, @(':n') to the @(':sysdef')
 query, and @('t') to all others.</p>

 <p>It remains only to discuss how the system prints text when the default
 value is not @('nil'), i.e., when the query is handled without interaction.
 In fact, it is allowed to pair a query id with a singleton list containing a
 keyword, rather than a keyword, and this indicates that no printing is to be
 done.  Thus for the example above, @(':sysdef') queries would be handled
 noninteractively, with printing done to simulate the interaction.  But if we
 change the example so that @(':sysdef') is paired with @('(:n)'), i.e., if
 @('ld-query-control-alist') is @(''((:filter . nil) (:sysdef :n) . t)'), then
 no such printing would take place for @('sysdef') queries.  Instead, the
 default value of @(':n') would be assigned ``quietly''.</p>")

(defxdoc ld-redefinition-action
  :parents (ld)
  :short "To allow redefinition without @(see undoing)"
  :long "<p>The present topic discusses redefining functions, macros, and
 constants, using a mechanism that may be convenient but also may be unsafe or
 unsound.  See @(see undo) for what is often a better way to carry out
 redefinition.</p>

 <p>@('Ld-redefinition-action') is an @(tsee ld) special (see @(see ld)).  The
 accessor is @('(ld-redefinition-action state)') and the updater is
 @('(set-ld-redefinition-action val state)').</p>

 <p><b>WARNING!</b> If @('ld-redefinition-action') is non-@('nil') then ACL2 is
 liable to be made unsafe or unsound, or behave in unexpected ways.  For
 example, redefining a macro or inlined function, @('f'), that is called in the
 body of another function, @('g'), may not cause the new version of @('f') to
 be called by @('g').  In addition, for some Lisps, in particular GCL Version
 2.7.0 or later, the return type @('TP') inferred for the original definition
 of @('f') might cause mishandling of the return value from @('f') as @('g')
 still expects that value's type to be @('TP').  Redefinition should be viewed
 as a way to facilitate unsafe, but potentially useful, hacking.</p>

 <p>The keyword command @(':')@(tsee redef) will set
 @('ld-redefinition-action') to a convenient setting allowing unsound
 redefinition.  See below.</p>

 <p>When @('ld-redefinition-action') is @('nil'), redefinition is prohibited.
 In that case, an error message is printed upon any attempt to introduce a name
 that is already in use.  There is one exception to this rule.  It is permitted
 to redefine a function symbol in @(':')@(tsee program) mode to be a function
 symbol in @(':')@(tsee logic) mode provided the formals and body remain the
 same.  This is the standard way a function ``comes into'' logical
 existence.</p>

 <p>Throughout the rest of this discussion we exclude from our meaning of
 ``redefinition'' the case in which a function in @(':')@(tsee program) mode is
 identically redefined in @(':')@(tsee logic) mode.  At one time, ACL2 freely
 permitted the @(see signature)-preserving redefinition of @(':')@(tsee
 program) mode functions but it no longer does.  See @(see
 redefining-programs).</p>

 <p>When @('ld-redefinition-action') is non-@('nil'), you are allowed to
 redefine a name that is already in use.  <b>The system may be rendered
 unsound</b> by such an act.  It is important to understand how dangerous
 redefinition is.  Suppose @('fn') is a function symbol that is called from
 within some other function, say @('g').  Suppose @('fn') is redefined so that
 its arity changes.  Then the definition of @('g') is rendered syntactically
 ill-formed by the redefinition.  This can be devastating since the entire ACL2
 system assumes that terms in its database are well-formed.  For example, if
 ACL2 executes @('g') by running the corresponding function in raw Common Lisp
 the redefinition of @('fn') may cause raw lisp to break in irreparable ways.
 As Lisp programmers we live with this all the time by following the simple
 rule: after changing the syntax of a function don't run any function that
 calls it via its old syntax.  This rule also works in the context of the
 evaluation of ACL2 functions, but it is harder to follow in the context of
 ACL2 deductions, since it is hard to know whether the database contains a path
 leading the theorem prover from facts about one function to facts about
 another.  Finally, of course, even if the database is still syntactically
 well-formed there is no assurance that all the rules stored in it are valid.
 For example, theorems proved about @('g') survive the redefinition of @('fn')
 but may have crucially depended on the properties of the old @('fn').  In
 summary, we repeat the warning: <b>all bets are off if you set</b>
 @('ld-redefinition-action') to <b>non</b>-@('nil').</p>

 <p>ACL2 provides some enforcement of the concern above, by disabling @(tsee
 certify-book) if any @(see world)-changing @(see events) exist in the
 certification @(see world) that were executed with a non-@('nil') value of
 @(''ld-redefinition-action').  (This value is checked at the end of each
 top-level command, but the value does not change during evaluation of embedded
 event forms; see @(see embedded-event-form).)</p>

 <p>If at any point in a session you wish to see the list of all names that
 have been redefined, see @(see redefined-names).</p>

 <p>That said, we'll give you enough rope to hang yourself.  When
 @('ld-redefinition-action') is non-@('nil'), it must be a pair, @('(a .  b)').
 The value of @('a') determines how the system interacts with you when a
 redefinition is submitted.  The value of @('b') allows you to specify how the
 property list of the redefined name is to be ``renewed'' before the
 redefinition.</p>

 <p>There are several dimensions to the space of possibilities controlled by
 part a: Do you want to be queried each time you redefine a name, so you can
 confirm your intention?  (We sometimes make typing mistakes or simply forget
 we have used that name already.)  Do you want to see a warning stating that
 the name has been redefined?  Do you want ACL2 system functions given special
 protection from possible redefinition?  Below are the choices for part a:</p>

 <blockquote>

 <p>@(':query') &mdash; every attempt to redefine a name will produce a query.
 The query will allow you to abort the redefinition or proceed.  It will will
 also allow you to specify the part @('b') for this redefinition.  @(':Query')
 is the recommended setting for users who wish to dabble in redefinition.</p>

 <p>@(':warn') &mdash; any user-defined function may be redefined but a
 post-redefinition warning is printed.  The attempt to redefine a system name
 produces a query.  If you are prototyping and testing a big system in ACL2
 this is probably the desired setting for part @('a').</p>

 <p>@(':doit') &mdash; any user-defined function may be redefined silently
 (without query or warning) but when an attempt is made to redefine a system
 function, a query is made.  This setting is recommended when you start making
 massive changes to your prototyped system (and tire of even the warning
 messages issued by @(':warn')).</p>

 </blockquote>

 <p>In support of our own ACL2 systems @(see programming) there are two other
 settings.  We suggest ordinary users not use them.</p>

 <blockquote>

 <p>@(':warn!') &mdash; every attempt to redefine a name produces a warning but
 no query.  Since ACL2 system functions can be redefined this way, this setting
 should be used by the only-slightly-less-than supremely confident ACL2 system
 hacker.</p>

 <p>@(':doit!') &mdash; this setting allows any name to be redefined silently
 (without query or warnings).  ACL2 system functions are fair game.  This
 setting is reserved for the supremely confident ACL2 system hacker.
 (Actually, this setting is used when we are loading massively modified
 versions of the ACL2 source files.)</p>

 </blockquote>

 <p>Part @('b') of @('ld-redefinition-action') tells the system how to
 ``renew'' the property list of the name being redefined.  There are two
 choices:</p>

 <blockquote>

 <p>@(':erase') &mdash; erase all properties stored under the name, or</p>

 <p>@(':overwrite') &mdash; preserve existing properties and let the redefining
 overwrite them.</p>

 </blockquote>

 <p>It should be stressed that neither of these @('b') settings is guaranteed
 to result in an entirely satisfactory state of affairs after the redefinition.
 Roughly speaking, @(':erase') returns the property list of the name to the
 state it was in when the name was first introduced.  Lemmas, type information,
 etc., stored under that name are lost.  Is that what you wanted?  Sometimes it
 is, as when the old definition is ``completely wrong.'' But other times the
 old definition was ``almost right'' in the sense that some of the work done
 with it is still (intended to be) valid.  In that case, @(':overwrite') might
 be the correct @('b') setting.  For example if @('fn') was a function and is
 being re-@(tsee defun)'d with the same @(see signature), then the properties
 stored by the new @(tsee defun) should overwrite those stored by the old
 @(tsee defun) but the properties stored by @(tsee defthm)s will be
 preserved.</p>

 <p>In addition, neither setting will cause ACL2 to erase properties stored
 under other symbols!  Thus, if @('FOO') names a rewrite rule which rewrites a
 term beginning with the function symbol @('BAR') and you then redefine
 @('FOO') to rewrite a term beginning with the function symbol @('BAZ'), then
 the old version of @('FOO') is still available (because the rule itself was
 added to the rewrite rules for @('BAR'), whose property list was not cleared
 by redefining @('FOO')).</p>

 <p>The @('b') setting is only used as the default action when no query is
 made.  If you choose a setting for part a that produces a query then you will
 have the opportunity, for each redefinition, to specify whether the property
 list is to be erased or overwritten.</p>

 <p>The keyword command @(':')@(tsee redef) sets @('ld-redefinition-action') to
 the pair @('(:query . :overwrite)').  Since the resulting query will give you
 the chance to specify @(':erase') instead of @(':overwrite'), this setting is
 quite convenient.  But when you are engaged in heavy-duty prototyping, you may
 wish to use a setting such as @(':warn') or even @(':doit').  For that you
 will have to invoke a form such as:</p>

 @({
  (set-ld-redefinition-action '(:doit . :overwrite) state) .
 })

 <p>@(tsee Encapsulate) causes somewhat odd interaction with the user if
 redefinition occurs within the encapsulation because the @(see encapsulate)d
 event list is processed several times.  For example, if the redefinition
 action causes a query and a non-local definition is actually a redefinition,
 then the query will be posed twice, once during each pass.  C'est la vie.</p>

 <p>Finally, it should be stressed again that redefinition is dangerous because
 not all of the rules about a name are stored on the property list of the name.
 Thus, redefinition can render ill-formed terms stored elsewhere in the
 database or can preserve now-invalid rules.  See @(see redundant-events), in
 particular the section ``Note About Unfortunate Redundancies,'' for more
 discussion of potential pitfalls of redefinition.</p>")

(defxdoc ld-skip-proofsp
  :parents (ld)
  :short "How carefully ACL2 processes your @(see command)s"
  :long "@({
  Examples:
  ACL2 !>(set-ld-skip-proofsp t state)
   T
  ACL2 !s>(set-ld-skip-proofsp nil state)
   NIL
  ACL2 !>(set-ld-skip-proofsp 'include-book state)
   INCLUDE-BOOK
  ACL2 !s>
 })

 <p>A global variable in the ACL2 @(tsee state), called @(''ld-skip-proofsp'),
 determines the thoroughness with which ACL2 processes your @(see command)s.
 This variable may take on one of three values: @('t'), @('nil') or
 @(''')@(tsee include-book).  When @('ld-skip-proofsp') is non-@('nil'), the
 system skips all proofs, which of course can render the system unsound.  The
 form @('(set-ld-skip-proofsp flg state)') is the general-purpose way of
 setting @('ld-skip-proofsp').  This global variable is an ``@(tsee ld)
 special,'' which is to say, you may call @(tsee ld) in such a way as to
 ``bind'' this variable for the dynamic extent of the @(tsee ld).</p>

 <p>When @('ld-skip-proofsp') is non-@('nil'), the default @(see prompt)
 displays the character @('s').  Thus, the @(see prompt)</p>

 @({
  ACL2 !s>
 })

 <p>means that the default @(see defun-mode) is @(':')@(tsee logic) (otherwise
 the character @('p'), for @(':')@(tsee program), would also be printed; see
 @(see default-print-prompt)) but ``proofs are being skipped.''</p>

 <p>Observe that there are two legal non-@('nil') values, @('t') and
 @(''')@(tsee include-book).  When @('ld-skip-proofsp') is @('t'), ACL2 skips
 all proof obligations but otherwise performs all other required analysis of
 input @(see events).  When @('ld-skip-proofsp') is @(''')@(tsee include-book),
 ACL2 skips not only proof obligations but all analysis except that required to
 compute the effect of successfully executed @(see events).  To explain the
 distinction, let us consider one particular event, say a @(tsee defun).  Very
 roughly speaking, a @(tsee defun) event normally involves a check of the
 syntactic well-formedness of the submitted definition, the generation and
 proof of the termination conditions, and the computation and storage of
 various rules such as a @(':')@(tsee definition) rule and some @(':')@(tsee
 type-prescription) rules.  By ``normally'' above we mean when
 @('ld-skip-proofsp') is @('nil').  How does a @(tsee defun) behave when
 @('ld-skip-proofsp') is non-@('nil')?</p>

 <p>If @('ld-skip-proofsp') is @('t'), then @(tsee defun) performs the
 syntactic well-formedness checks and computes and stores the various rules,
 but it does not actually carry out the termination proofs.  If
 @('ld-skip-proofsp') is @(''')@(tsee include-book), @(tsee defun) does not do
 the syntactic well-formedness check nor does it carry out the termination
 proof.  Instead, it merely computes and stores the rules under the assumption
 that the checks and proofs would all succeed.  Observe that a setting of
 @(''')@(tsee include-book) is ``stronger'' than a setting of @('t') in the
 sense that @(''')@(tsee include-book) causes @(tsee defun) to assume even more
 about the admissibility of the event than @('t') does.</p>

 <p>As one might infer from the choice of name, the @(tsee include-book) event
 sets @('ld-skip-proofsp') to @(''')@(tsee include-book) when processing the
 @(see events) in a book being loaded.  Thus, @(tsee include-book) does the
 minimal work necessary to carry out the effects of every event in the book.
 The syntactic checks and proof obligations were, presumably, successfully
 carried out when the book was certified.</p>

 <p>A non-@('nil') value for @('ld-skip-proofsp') also affects the system's
 output messages.  Event summaries (the paragraphs that begin ``@(see
 Summary)'' and display the event forms, rules used, etc.) are not printed when
 @('ld-skip-proofsp') is non-@('nil').  Warnings and observations are printed
 when @('ld-skip-proofsp') is @('t') but are not printed when it is
 @(''')@(tsee include-book).</p>

 <p>Intuitively, @('ld-skip-proofsp') @('t') means skip just the proofs and
 otherwise do all the work normally required for an event; while
 @('ld-skip-proofsp') @(''')@(tsee include-book) is ``stronger'' and means do
 as little as possible to process @(see events).  In accordance with this
 intuition, @(tsee local) @(see events) are processed when @('ld-skip-proofsp')
 is @('t') but are skipped when @('ld-skip-proofsp') is @(''')@(tsee
 include-book).</p>

 <p>The ACL2 system itself uses only two settings, @('nil') and @(''')@(tsee
 include-book), the latter being used only when executing the @(see events)
 inside of a book being included.  The @('ld-skip-proofsp') setting of @('t')
 is provided as a convenience to the user.  For example, suppose one has a file
 of @(see events).  By loading it with @(tsee ld) with @('ld-skip-proofsp') set
 to @('t'), the @(see events) can all be checked for syntactic correctness and
 assumed without proof.  This is a convenient way to recover a state lost by a
 system crash or to experiment with a modification of an @(see events)
 file.</p>

 <p>The foregoing discussion is actually based on a lie.  @('ld-skip-proofsp')
 is allowed two other values, @(''initialize-acl2') and
 @(''include-book-with-locals').  The first causes behavior similar to @('t')
 but skips @(tsee local) @(see events) and avoids some error checks that would
 otherwise prevent ACL2 from properly booting.  The second is identical to
 @(''')@(tsee include-book) but also executes @(tsee local) @(see events).
 These additional values are not intended for use by the user, but no barriers
 to their use have been erected.</p>

 <p>User-defined tools may temporarily modify the global setting of
 @('ld-skip-proofsp'); for example, see @(see remove-hyps).</p>

 <p>We close by reminding the user that ACL2 is potentially unsound if
 @('ld-skip-proofsp') is set by the user.  Indeed, direct setting of
 @('ld-skip-proofsp') is illegal within a book (except during @(tsee
 make-event) expansion).  We provide access to it simply to allow
 experimentation and rapid reconstruction of lost or modified logical @(see
 world)s.</p>")

(defxdoc ld-verbose
  :parents (ld)
  :short "Determines whether @(tsee ld) prints ``ACL2 Loading ...''"
  :long "<p>@('Ld-verbose') is an @(tsee ld) special (see @(see ld)).  The
 accessor is @('(ld-verbose state)') and the updater is @('(set-ld-verbose val
 state)').  @('Ld-verbose') must be @('t'), @('nil') or a string or @(tsee
 consp) suitable for @(tsee fmt) printing via the @('~@') command.  The initial
 value of @('ld-verbose') is a @(tsee fmt) message that prints the system books
 directory.</p>

 <p>Note: @('Ld-verbose') has no effect on proofs.  See @(see set-gag-mode) and
 see @(see set-inhibit-output-lst) for how to control the size of proof
 output.</p>

 <p>Before processing the forms in @(tsee standard-oi), @(tsee ld) may print a
 header.  The printing of this header is controlled by @('ld-verbose').  If
 @('ld-verbose') is @('nil'), no header is printed.  If it is @('t'), @(tsee
 ld) prints the message</p>

 @({
     ACL2 loading <file>
 })

 <p>where @('<file>') is the input channel supplied to @(tsee ld).  A similar
 message is printed when @(tsee ld) completes.  If @('ld-verbose') is neither
 @('t') nor @('nil') then it is presumably a header and is printed with the
 @('~@') @(tsee fmt) directive before @(tsee ld) begins to read and process
 forms.  In this case the @('~@') @(tsee fmt) directive is interpreted in an
 environment in which @('#\b') is the system books directory, @('#\v') is the
 ACL2 version string, @('#\l') is the level of the current recursion in @(tsee
 ld) and/or @(tsee wormhole), and @('#\c') is the connected book directory
 @('(cbd)').</p>")

(defxdoc lemma-instance
  :parents (hints functional-instantiation)
  :short "An object denoting an instance of a theorem"
  :long "<p>Lemma instances are the objects one provides via @(':use') and
 @(':by') @(see hints) to bring to the theorem prover's attention some
 previously proved or easily provable fact.  A typical use of the @(':use')
 hint is given below.  The value specified is a list of five lemma
 instances.</p>

 @({
  :use (reverse-reverse
        (:type-prescription app)
        (:instance assoc-of-app
                   (x a) (y b) (z c))
        (:functional-instance p-f
                              (p consp) (f flatten))
        (:instance (:theorem (equal x x))
                   (x (flatten a))))
 })

 <p>Observe that an event name can be a lemma instance.  The @(':use') hint
 allows a single lemma instance to be provided in lieu of a list, as in:</p>

 @({
  :use reverse-reverse
 })

 <p>or</p>

 @({
  :use (:instance assoc-of-app (x a) (y b) (z c))
 })

 <p>A lemma instance denotes a formula which is either known to be a theorem or
 which must be proved to be a theorem before it can be used.  To use a lemma
 instance in a particular subgoal, the theorem prover adds the formula as a
 hypothesis to the subgoal before the normal theorem proving heuristics are
 applied.</p>

 <p>A lemma instance, or @('lmi'), is of one of the following forms:</p>

 <p>(1) @('name'), where @('name') names a previously proved theorem, axiom, or
 definition and denotes the formula (theorem) of that name.</p>

 <p>(2) @('rune'), where @('rune') is a @(see rune) (see @(see rune)) denoting
 the @(':')@(tsee corollary) justifying the rule named by the @(see rune).</p>

 <p>(3) @('(:theorem term)'), where @('term') is any term alleged to be a
 theorem.  Such a lemma instance denotes the formula @('term').  But before
 using such a lemma instance the system will undertake to prove @('term').</p>

 <p>(4) @('(:instance lmi (v1 t1) ... (vn tn))'), where @('lmi') is recursively
 a lemma instance, the @('vi')'s are distinct variables, and the @('ti')'s are
 terms.  Such a lemma instance denotes the formula obtained by instantiating
 the formula @('F') denoted by @('lmi'), normally by replacing each @('vi') by
 @('ti') in @('F') and requiring that each @('vi') must be bound in @('F').
 There are two exceptions.  If the keyword @(':extra-bindings-ok') is inserted
 immediately after the lemma instance in order to remove that requirement, as
 follows, then that requirement is ignored: @('(:instance
 lmi :extra-bindings-ok (v1 t1) ... (vn tn))').  Otherwise there is the
 following exception pertaining to @(see packages): if one or more variables
 @('vi') do not occur in @('F'), but for each such @('vi') exactly one variable
 @('v') with the same @(tsee symbol-name) as @('vi') occurs in @('F') and no
 other @('vj') with the same @('symbol-name') as @('v') is bound in the
 substitution, then the pair @('(vi ti)') is replaced by the pair @('(v ti)')
 in the substitution.</p>

 <p>(5) @('(:functional-instance lmi (f1 g1) ... (fn gn))'), where @('lmi') is
 recursively a lemma instance and each @('fi') is an ``instantiable'' function
 symbol of arity @('ni') and @('gi') is a function symbol, a macro alias for a
 function symbol @('gi'') (see @(see macro-aliases-table)) in which case we
 treat @('gi') as @('gi''), or a pseudo-lambda expression of arity @('ni').  An
 instantiable function symbol is any defined or constrained function symbol
 except the primitives @(tsee not), @(tsee member), @(tsee implies), and @(tsee
 o<), and a few others, as listed by the constant
 @('*non-instantiable-primitives*').  These are built-in in such a way that we
 cannot recover the @(see constraint)s on them.  (Special case: a function
 introduced in the @(':partial-theory') of a dependent clause-processor is not
 instantiable; see @(see define-trusted-clause-processor).)  A pseudo-lambda
 expression is an expression of the form @('(lambda (v1 ... vn) body)') where
 the @('vi') are distinct variable symbols and @('body') is any term.  No <i>a
 priori</i> relation is imposed between the @('vi') and the variables of
 @('body'), i.e., @('body') may ignore some @('vi')'s and may contain ``free''
 variables.  However, we do not permit @('v') to occur freely in @('body') if
 the functional substitution is to be applied to any formula (@('lmi') or the
 @(see constraint)s to be satisfied) in a way that inserts @('v') into the
 scope of a binding of @('v') by @(tsee let) or @(tsee mv-let) (or, @(tsee
 lambda)).  If you happen to violate this restriction, an informative error
 message will be printed.  That message will list for you the potentially
 illegal choices for @('v') in the context in which the functional substitution
 is offered.  A @(':functional-instance') lemma instance denotes the formula
 obtained by functionally instantiating the formula denoted by @('lmi'),
 replacing @('fi') by @('gi').  However, before such a lemma instance can be
 used, the system will generate proof obligations arising from the replacement
 of the @('fi')'s by the @('gi')'s in constraints that ``support'' the lemma to
 be functionally instantiated; see @(see constraint).  One might expect that if
 the same instantiated constraint were generated on behalf of several events,
 then each of those instances would have to be proved.  However, for the sake
 of efficiency, ACL2 stores the fact that such an instantiated constraint has
 been proved, unless the proof was done inside an @(tsee encapsulate) event
 that either has a non-empty @(see signature) list or is ``empty'' (stores
 no events), and then avoids re-proving that constraint in future @(see
 events).</p>

 <p>See @(see functional-instantiation-example) for an example of the use of
 @(':functional-instance') (so-called ``functional instantiation'').  See
 @(tsee set-constraint-tracking) for help figuring out where subgoals generated
 by @(':functional-instance') hints came from.</p>

 <p>Note that ACL2(r) (see @(see real)) imposes additional requirements for
 functional instantiation.  See @(see functional-instantiation-in-acl2r).</p>

 <p>(6) @('(:termination-theorem name)') or @('(:termination-theorem! name)'),
 where @('name') is a function symbol in @(see logic) mode.  Such a lemma
 instance denotes the termination theorem previously proved for @('name'),
 possibly modified as discussed in the next paragraph.  If no such theorem
 exists &mdash; for example, if the definition of @('name') is not recursive
 &mdash; then the lemma instance is illegal in the case of
 @(':termination-theorem'), but denotes @('T') in the case of
 @(':termination-theorem!').  If @('name') is defined as part of a
 mutually-recursive clique of definitions (see @(see mutual-recursion)), then
 the lemma instance refers to the termination theorem proved for the entire
 clique.  See @(see termination-theorem-example) and see @(see tthm).</p>

 <p>Consider the application of @(':termination-theorem f') while attempting to
 prove the termination theorem for a function, @('g').  For now suppose that
 neither @('f') nor @('g') is defined using @(tsee mutual-recursion).  Suppose
 that @('f') and @('g') have the same number of formal parameters.  Then every
 call of @('f') in the termination theorem for @('f') will be replaced by a
 call of @('g') on the same arguments (except, recursively, @('f') is also
 replaced by @('g') in those arguments).  The analogous replacement also takes
 place for mutually recursive definitions, as follows.  In the case that @('f')
 was introduced with @('(mutual-recursion (defun f1 ...) ... (defun fk ...))')
 and similarly @('g') is being introduced with @('(mutual-recursion (defun g1
 ...)  ... (defun gk ...))'), where for each @('i') from @('1') to @('k') the
 number of formal parameters is the same for @('fi') and @('gi'), then the
 functional substitution @('((f1 . g1) ... (fk . gk))') is applied to the
 termination theorem for the @('fi').  (Logical justification in a nutshell:
 the termination proof for the @('fi') took place before adding their
 definitional equations to the current theory, where the @('fi') were thus
 stubs with no axioms.)  Note that unlike normal @(see
 functional-instantiation), here there is no proof obligation.  However, the
 restriction applies from (5) above that the functions @('fi') are
 instantiable; when that fails, then the replacement of each @('fi') by @('gi')
 will not take place.</p>

 <p>Finally, note that an optional second argument to @(':termination-theorem')
 specifies an explicit functional substitution @('((f1 g1) ... (fn gn))'),
 which is to be applied to the termination theorem for @('f').  If that
 argument is supplied, then there will be no attempt to derive a functional
 substitution automatically, as described in the preceding paragraph.</p>

 <p>(7) @('(:guard-theorem name)') or @('(:guard-theorem name simplify)'),
 where @('name') is a @(see guard)-verified function symbol (hence, in
 particular, is in @(see logic) mode).  Such a lemma instance denotes the guard
 theorem previously proved for @('name'), where by default @('simplify') is
 @(':limited'), which enables certain simplifications as documented elsewhere;
 see @(see gthm).  Otherwise @('simplify') should be @('nil'), to avoid all
 such simplification.  If @('name') is defined as part of a mutually-recursive
 clique of definitions (see @(see mutual-recursion)), then the lemma instance
 refers to the guard theorem proved for the entire clique.  See @(see
 guard-theorem-example) and see @(see gthm).</p>

 <p>Obscure case for @(see definition)s.  If the lemma instance refers to a
 @(':definition') @(see rune), then it refers to the @(tsee corollary) formula
 of that rune, which can be a normalized (simplified) form of the definition
 body; see @(see normalize).  However, if the hint is a @(':by') hint and the
 lemma instance is based on a name (i.e., a symbol), rather than a rune, then
 the formula is the original formula of the event, as shown by @(':')@(tsee
 pe), rather than the normalized version, as shown by @(':')@(tsee pf).  This
 is as one would expect: If you supply the name of an event, you expect it to
 refer to the original event.  For @(':use') hints we use the simplified (@(see
 normalize)d) form instead, which is reasonable since one would expect
 simplification during the proof that re-traces the normalization done at the
 time the rule was created.</p>

 <p>We conclude with remarks on (6) and (7).  The termination theorem actually
 used is an unsimplified version of what was originally proved for the
 indicated function; the guard theorem is, by default, partially simplified.
 That is: while in general, the termination theorem is simplified before being
 given to the prover, nevertheless the unsimplified theorem is what is actually
 used for @(':termination-theorem') lemma instances; for @(':guard-theorem'),
 some simplification is done that is independent of the theory, by using a form
 of ``subsumption'' to eliminate redundancy and by deleting tautologies as well
 as instances of @(see built-in-clause) rules that come with ACL2.  Also see
 @(see guard-formula-utilities) and @(see guard-simplification).  Moreover, the
 @(':')@(tsee measure-debug) and @(':')@(tsee guard-debug) keywords for @(tsee
 xargs) are ignored when generating the termination or guard theorem.  You can
 see the termination or guard theorem for an existing function symbol @('FN')
 by evaluating the form @('(termination-theorem 'FN (w state))') or
 @('(guard-theorem 'FN simplify guard-debug (w state) state)'), respectively.
 In the former case, failure is indicated by a result of the form @('(FAILED
 . msg)'), where @('msg') is a message suitable for @(tsee fmt); see @(see
 msg).</p>

 <p>Also see @(see make-termination-theorem).</p>

 <p>Why do we avoid simplification for @(':termination-theorem'), as described
 in the preceding paragraph?  The reason is that it could in principle
 strengthen the theorem, which is sound when admitting the original function
 but not for lemma instances.  Future work might try to allow simplification at
 lemma-instance time, by ensuring that simplification never strengthens the
 theorem.  Alternatively, simplification might be checked for each usage to be
 equivalence-preserving by defining a suitable macro based on @(tsee
 make-event).  For now, by avoiding simplification we guarantee that the
 theorem we are using is truly a theorem.  The theorem being used might not be
 exactly the theorem originally proved, for example because of the use of @(see
 case-split-limitations), which depends on the current logical @(see world);
 but we expect the two theorems to be logically equivalent.</p>")

(defxdoc len
  :parents (lists acl2-built-ins)
  :short "Length of a list"
  :long "<p>@('Len') returns the length of a list.</p>

 <p>A Common Lisp function that is appropriate for both strings and proper
 lists is @('length'); see @(see length).  The guard for @('len') is
 @('t').</p>

 <p>(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.)</p>

 @(def len)")

(defxdoc length
  :parents (lists strings acl2-built-ins)
  :short "Length of a string or proper list"
  :long "<p>@('Length') is the function for determining the length of a
 sequence.  In ACL2, the argument is required to be either a @(tsee true-listp)
 or a string.</p>

 <p>For a similar function that is logically defined to be equal to zero on any
 atom, including any string, see @(tsee len).</p>

 <p>@('Length') is a Common Lisp function.  See any Common Lisp documentation
 for more information.</p>

 @(def length)")

(defxdoc let
  :parents (basics acl2-built-ins)
  :short "Binding of lexically scoped (local) variables"
  :long "<h3>Introduction</h3>

 <p>Example</p>

 @({
  (let ((x (* x x))
        (y (* 2 x)))
   (list x y))
 })

 <p>If the form above is executed in an environment in which @('x') has the
 value @('-2'), then the result is @(''(4 -4)').</p>

 <p>@('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)').</p>

 <p>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)').</p>

 <p>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)').</p>

 <p>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:</p>

 @({
  (let* ((x (* x x))
         (y (* 2 x)))
   (list x y))
 })

 <p>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').  @(tsee Let*) binds its local variables
 ``sequentially.''</p>

 <p>General @('let') forms</p>
 @({
  (let ((var1 term1) ... (varn termn)) body)
  and
  (let ((var1 term1) ... (varn termn))
   (declare ...) ... (declare ...)
   body)
 })

 <p>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 @(see declare)d ignored.  In ACL2 the only @(tsee declare)
forms allowed for a @('let') form are  @('ignore'), @('ignorable'), and
@('type').  See @(see declare).</p>

 <p>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.</p>

 <p>Actually, @('let') forms are just abbreviations for certain uses of
 @('lambda') notation.  In particular</p>

 @({
  (let ((var1 term1) ... (varn termn)) (declare ...) body)
 })

 <p>is equivalent to</p>

 @({
  ((lambda (var1 ... varn)
     (declare ...)
     body)
   term1 ... termn).
 })

 <p>@(tsee 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').</p>

 <p>General @('let*') forms:</p>
 @({
  (let* ((var1 term1) ... (varn termn)) body)
  and
  (let* ((var1 term1) ... (varn termn))
   (declare (ignore x1 ... xm))
   body)
 })

 <p>where the @('vari') are variables (not necessarily distinct), the
 @('termi') are terms involving only variables bound in the environment
 containing the @(tsee 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 @(tsee 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 @(tsee let*) does not
 permit the inclusion of any @(tsee 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').</p>

 <p>The first @(tsee let*) above is equivalent to</p>

 @({
  (let ((var1 term1))
   ...
   (let ((varn termn)) body)...)
 })

 <p>Thus, the @('termi') are evaluated successively and after each evaluation
 the corresponding @('vari') is bound to the value of @('termi').  The second
 @(tsee 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))').</p>

 <p>Each @('(vari termi)') pair in a @('let') or @(tsee let*) form is called a
 ``binding'' of @('vari') and the @('vari') are called the ``local variables''
 of the @('let') or @(tsee let*).  The common use of @('let') and @(tsee 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.</p>

 <p>@('Let') is part of Common Lisp.  See any Common Lisp documentation for
 more information.</p>")

(defxdoc let*
  :parents (basics acl2-built-ins)
  :short "Binding of lexically scoped (local) variables"
  :long "<p>Examples</p>

 @({
  (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))
 })

 <p>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 @(see let) for a discussion of both @(tsee let) and @('let*'), or read on
 for a briefer discussion.</p>

 <p>The difference between @(tsee 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 @(see let).</p>

 <p>In ACL2 the only @(tsee declare) forms allowed for a @('let*') form are
 @('ignore'), @('ignorable'), and @('type').  See @(see declare).  Moreover, no
 variable declared @('ignore')d 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.</p>

 <p>@('Let*') is a Common Lisp macro.  See any Common Lisp documentation for
 more information.</p>")

(defxdoc lexorder
  :parents (<< acl2-built-ins)
  :short "Total order on ACL2 objects"
  :long "<p>@('Lexorder') is a non-strict total order, a ``less than or
 equal,'' on ACL2 objects.  Also see @(see alphorder), the restriction of
 @('lexorder') to atoms; the notion of ``non-strict total order'' is defined
 there.</p>

 <p>@('Lexorder') has a guard of @('t').</p>

 <p>For @('lexorder'), an @(see atom) and a @(see cons) are ordered so that the
 @(see atom) comes first, and two @(see cons)es are ordered so that the one
 with the recursively smaller @(tsee car) comes first, with the @(tsee cdr)s
 being compared only if the @(tsee car)s are equal.  @('Lexorder') compares two
 atoms by using @(tsee alphorder).</p>

 @(def lexorder)")

(defxdoc linear
  :parents (rule-classes)
  :short "Make some arithmetic inequality rules"
  :long "<p>See @(see rule-classes) for a general discussion of rule classes,
 including how they are used to build rules from formulas and a discussion of
 the various keywords in a rule class description.</p>

 @({
  Example:
  (defthm length-member-leq-length       If inequality reasoning begins to
    (implies (and (eqlablep e)           consider how (length (member a b))
                  (true-listp x))        compares to any other term, add to
             (<= (length (member e x))   the set of known inequalities the fact
                 (length x)))            that it is no larger than (length b),
    :rule-classes :linear)               provided (eqlablep a) and
                                         (true-listp b) rewrite to t.

  General Form:
  (and ...
       (implies (and ...hi...)
                (implies (and ...hk...)
                         (and ...
                              (rel lhs rhs)
                              ...)))
       ...)
 })

 <p>We process the @(':')@(tsee corollary) formula of one @(':linear') rule
 class object to create one or more @(':linear') rules.  The first step is to
 flatten the @(tsee and) and @(tsee implies) structure of the formula,
 transforming it into a conjunction of formulas, each of the form</p>

 @({
  (implies (and h1 ... hn) (rel lhs rhs))
 })

 <p>where no hypothesis is a conjunction and the term @('(rel lhs rhs)') is a
 call of one of the inequality relations @(tsee <), @(tsee <=), @(tsee >), or
 @(tsee >=); the negation of such a call; a call of @(tsee =) or @(tsee equal);
 or a negated call of @(tsee /=).  Note that we refer to all of these terms as
 ``inequalities'' below, even the equalities.  If necessary, the hypothesis of
 such a conjunct may be vacuous.  We create a @(':linear') rule for each such
 conjunct, if possible, and otherwise cause an error.  To create a @(':linear')
 rule from a term (i.e., from a single such conjunct), we apply the following
 sequence of transformations (as well as macroexpansion, which removes calls of
 @(tsee <=), @(tsee >), and @(tsee >=)).</p>

 <ol>

 <li>Remove @(see guard-holders) such as @(tsee prog2$) from the term to obtain
 @('(implies hyp concl)'), where @('hyp') is @('t') in the case of an
 unconditional rule.</li>

 <li>If @('concl') is @('(not (not concl2))'), replace @('concl') by
 @('concl2').</li>

 <li>For the resulting @('concl'), replace @(tsee =) and @(tsee /=) by @(tsee
 equal) and @('not equal'), respectively.</li>

 </ol>

 <p>Each rule has one or more ``trigger terms'' which may be specified by the
 user using the @(':trigger-terms') field of the rule class or which may be
 defaulted to values chosen by the system.  We discuss the determination of
 trigger terms after discussing how linear rules are used.</p>

 <p>@(':Linear') rules are used by an arithmetic decision procedure during
 rewriting.  See @(see linear-arithmetic) and see @(see non-linear-arithmetic).
 Here we assume that the reader is familiar with the material described in
 @(tsee linear-arithmetic).</p>

 <p>Recall that we eliminate the unknowns of an inequality in term-order,
 largest unknowns first.  (See @(see term-order).)  In order to facilitate this
 strategy, we store the inequalities in ``linear pots''.  For purposes of the
 present discussion, let us say that an inequality is ``about'' its largest
 unknown.  Then, all of the inequalities about a particular unknown are stored
 in the same linear pot, and the pot is said to be ``labeled'' with that
 unknown.  This storage layout groups all of the inequalities which are
 potential candidates for cancellation with each other into one place.  It is
 also key to the efficient operation of @(':linear') rules.</p>

 <p>If the arithmetic decision procedure has stabilized and not yielded a
 contradiction, we scan through the list of linear pots examining each label as
 we go.  If the trigger term of some @(':linear') rule can be instantiated to
 match the label, we so instantiate that rule and attempt to relieve the
 hypotheses with general-purpose rewriting.  If we are successful, we rewrite
 each of the two terms being compared by the conclusion (which is an equality
 or inequality), under the substitution produced by the rule's instantiation.
 We then add the resulting equality or inequality to our set of
 inequalities. This may let cancellation continue.</p>

 <p>Note: Problems may arise if you explicitly store a linear lemma under a
 trigger term that, when instantiated, is not the largest unknown in the
 instantiated concluding inequality.  Suppose for example you store the linear
 rule @('(<= (fn i j) (/ i (* j j)))') under the trigger term @('(fn i j)').
 Then when the system ``needs'' an inequality about @('(fn a b)'), (i.e.,
 because @('(fn a b)') is the label of some linear pot, and hence the largest
 unknown in some inequality), it will appeal to the rule and deduce @('(<= (fn
 a b) (/ a (* b b)))').  However, the largest unknown in this inequality is
 @('(/ a (* b b))') and hence it will be stored in a linear pot labeled with
 @('(/ a (* b b))').  The original, triggering inequality which is in a pot
 about @('(fn a b)') will therefore not be canceled against the new one.  It
 is generally best to specify as a trigger term one of the ``maximal'' terms of
 the polynomial, as described below.</p>

 <p>We now describe how the trigger terms are determined.  Most of the time,
 the trigger terms are not specified by the user and are instead selected by
 the system.  However, the user may specify the terms by including an explicit
 @(':trigger-terms') field in the rule class, e.g.,</p>

 @({
  General Form of a Linear Rule Class:
  (:LINEAR :COROLLARY formula
           :TRIGGER-TERMS (term1 ... termk))
 })

 <p>Each @('termi') must be a term and must not be a variable, quoted constant,
 lambda application, @('let-expression') or @('if-expression').  In addition,
 each @('termi') must be such that if all the variables in the term are
 instantiated and then the hypotheses of the corollary formula are relieved
 (possibly instantiating additional free variables), then all the variables in
 the concluding inequality are instantiated.  We generate a linear rule for
 each conjunctive branch through the corollary and store each rule under each of
 the specified triggers.  Thus, if the corollary formula contains several
 conjuncts, the variable restrictions on the @('termi') must hold for each
 conjunct.</p>

 <p>If @(':trigger-terms') is omitted the system computes a set of trigger
 terms.  Each conjunct of the corollary formula may be given a unique set of
 triggers depending on the variables that occur in the conjunct and the addends
 that occur in the concluding inequality.  In particular, the trigger terms for
 a conjunct is the list of all ``maximal addends'' in the concluding inequality
 after replacing, where possible based on the @(see current-theory), ground
 subterms (those that have no free variables) with their values.</p>

 <p>The ``addends'' of @('(+ x y)') and @('(- x y)') are the union of the
 addends of @('x') and @('y').  The addends of @('(- x)') and @('(* n x)'),
 where @('n') is a rational constant, is just @('{x}').  The addends of an
 inequality are the union of the addends of the left- and right-hand sides.
 The addends of any other term, @('x'), is @('{x}').</p>

 <p>A term is maximal for a conjunct @('(implies hyps concl)') of the corollary
 if (a) the term is a non-variable, non-quote, non-lambda application,
 non-@(tsee let) and non-@(tsee if) expression, (b) the term contains enough
 variables so that when they are instantiated and the hypotheses are relieved
 (which may bind some free variables; see @(see free-variables)) then all the
 variables in @('concl') are instantiated, and (c) no other addend is always
 ``bigger'' than the term, in the technical sense described below.  Note that
 the notion of ``enough variables'' in (b) is affected by hypotheses that are
 calls of @('bind-free'); see @(see bind-free).</p>

 <p>The technical notion referenced above depends on the notion of
 <i>fn-count</i>, the number of function symbols in a term, and
 <i>pseudo-fn-count</i>, which is essentially the number of function symbols
 implicit in a constant (see @(see term-order), specifically the discussion of
 ``pseudo-function application count'' at the end).  We say @('term1') is
 always bigger than @('term2') if all instances of @('term1') have a larger
 fn-count (actually lexicographic order of fn-count and pseudo-fn-count) than
 the corresponding instances of @('term2').  This is equivalent to saying that
 the fn-count of @('term1') is larger than that of @('term2') (by ``fn-count''
 here we mean the lexicographic order of fn-count and pseudo-fn-count) and the
 variable bag for @('term2') is a subbag of that for @('term1').  For example,
 @('(/ a (* b b))') is always bigger than @('(fn a b)') because the first has
 two function applications and @('{a b}') is a subbag of @('{a b b}'), but
 @('(/ a (* b b))') is not always bigger than @('(fn a x)').</p>

 <p>We conclude by noting that linear rules are useless when all of the
 polynomial's terms are provably non-numeric.  If ACL2 determines that to be
 the case for one or more of the conclusions, then it causes an error, except
 when @(':trigger-terms') is supplied explicitly by the user.</p>")

(defxdoc linear-arithmetic
  :parents (linear)
  :short "A description of the linear arithmetic decision procedure"
  :long "<p>ACL2 incorporates a rational linear arithmetic decision procedure.
 When the ACL2 prover attempts to simplify a goal, it first constructs a data
 structure, called the ``linear pot list'' (see @(see linear)), that records
 inequalities derived from the current goal, as an early step in the
 simplification process.  The linear pot list is constructed as follows: first,
 it is seeded with equalities and inequalities about arithmetic terms occurring
 in the goal to be proved; then, it is extended by instantiating @(':')@(tsee
 linear) lemmas about terms already in the pot list.  The resulting pot list is
 then supplied to the decision procedure when the rewriter is trying to
 establish or refute an arithmetic equality or inequality.  This happens, for
 example, when an inequality occurs as a hypothesis of a rule being applied by
 the rewriter.  (For discussion of the rewriter in general, see @(see
 introduction-to-rewrite-rules-part-1) and @(see
 introduction-to-rewrite-rules-part-2).)</p>

 <p>We describe the procedure very roughly here.  Fundamental to the
 procedure is the notion of a linear polynomial inequality.  A ``linear
 polynomial'' is a sum of terms, each of which is the product of a rational
 constant and an ``unknown.''  The ``unknown'' is permitted to be @('1') simply
 to allow a term in the sum to be constant.  Thus, an example linear polynomial
 is @('3*x + 7*a + 2'); here @('x') and @('a') are the (interesting) unknowns.
 However, the unknowns need not be variable symbols.  For example, @('(length
 x)') might be used as an unknown in a linear polynomial.  Thus, another linear
 polynomial is @('3*(length x) + 7*a').  A ``linear polynomial inequality'' is
 an inequality (either @(tsee <) or @(tsee <=)) relation between two linear
 polynomials.  Note that an equality may be considered as a pair of
 inequalities; e.q., @('3*x + 7*a + 2 = 0') is the same as the conjunction of
 @('3*x + 7*a + 2 <= 0') and @('0 <= 3*x + 7*a + 2').</p>

 <p>Certain linear polynomial inequalities can be combined by
 cross-multiplication and addition to permit the deduction of a third
 inequality with fewer unknowns.  If this deduced inequality is manifestly
 false, a contradiction has been deduced from the assumed inequalities.</p>

 <p>For example, suppose we have two assumptions</p>

 @({
  p1:       3*x + 7*a <  4
  p2:               3 <  2*x
 })

 <p>and we wish to prove that, given @('p1') and @('p2'), @('a < 0').  As
 suggested above, we proceed by assuming the negation of our goal</p>

 @({
  p3:               0 <= a.
 })

 <p>and looking for a contradiction.</p>

 <p>Our first step will be to eliminate the variable @('x').  To that end, we
 cross-multiply based on the coefficients of @('x') in the two inequalities.
 By multiplying @('p1') by @('2') and @('p2') by @('3'), and then adding the
 respective sides, we deduce the intermediate result</p>

 @({
  p4:  6*x + 14*a + 9 < 8 + 6*x
 })

 <p>which, after cancellation, is:</p>

 @({
  p4:        14*a + 1 <  0.
 })

 <p>If we then cross-multiply and add @('p3') to @('p4'), we get</p>

 @({
  p5:               1 <= 0,
 })

 <p>a contradiction.  Thus, we have proved that @('p1') and @('p2') imply the
 negation of @('p3').</p>

 <p>All of the unknowns of an inequality must be eliminated by cancellation in
 order to produce a constant inequality.  We can choose to eliminate the
 unknowns in any order, but we eliminate them in term-order, largest unknowns
 first.  (See @(see term-order).)  That is, two polys are canceled against
 each other only when they have the same largest unknown.  For instance, in the
 above example we see that @('x') is the largest unknown in each of @('p1') and
 @('p2'), and @('a') in @('p3') and @('p4').</p>

 <p>Now suppose that this procedure does not produce a contradiction but
 instead yields a set of nontrivial inequalities.  A contradiction might still
 be deduced if we could add to the set some additional inequalities allowing
 further cancellations.  That is where @(':linear') lemmas come in.  When the
 set of inequalities has stabilized under cross-multiplication and addition and
 no contradiction is produced, we search the database of @(':')@(tsee linear)
 rules for rules about the unknowns that are candidates for cancellation (i.e.,
 are the largest unknowns in their respective inequalities).  See @(see linear)
 for a description of how @(':')@(tsee linear) rules are used.</p>

 <p>See also @(tsee non-linear-arithmetic) for a description of an extension to
 the linear-arithmetic procedure described here.</p>")

(defxdoc list
  :parents (lists acl2-built-ins)
  :short "Build a list"
  :long "<p>@('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 @(see list*).</p>

 <p>If a call of @('list') results in an error due to too many arguments,
 consider using @(tsee list$).</p>

 <p>@('List') is defined in Common Lisp.  See any Common Lisp documentation for
 more information.</p>

 @(def list)
 @(def list-macro)")

(defxdoc list$
  :parents (lists acl2-built-ins)
  :short "Build a list"
  :long "<p>@('List$') is a macro that is virtually interchangeable with @(tsee
 list).  The only difference is that when the host Lisp is @(see GCL) with GCL
 version at least 2.7.0, @('list') may cause an error when given too many
 arguments (generally, more than 63).  In such cases, @('list$') may be used in
 place of @('list'), since @('list$') has no restriction on the number of
 arguments.</p>")

(defxdoc list*
  :parents (lists acl2-built-ins)
  :short "Build a list"
  :long "<p>@('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 @(see list).</p>

 <p>@('List*') is a Common Lisp function.  See any Common Lisp documentation
 for more information.</p>

 @(def list*)
 @(def list*-macro)")

(defxdoc listp
  :parents (lists conses acl2-built-ins)
  :short "Recognizer for (not necessarily proper) lists"
  :long "<p>@('(listp x)') is true when @('x') is either a @(tsee cons) pair or
 is @('nil').</p>

 <p>@('Listp') has no @(see guard), i.e., its @(see guard) is @('t').</p>

 <p>@('Listp') is a Common Lisp function.  See any Common Lisp documentation
 for more information.</p>

 @(def listp)")

(defxdoc lists
  :parents (programming)
  :short "Lists of objects, the classic Lisp data structure.")

(defxdoc live-stobj-in-proof
  :parents (raw-lisp-error)
  :short "Error messages about “live” @(see stobj)s during proofs"
  :long "<p>It is possible to see an error like the following.  (This error is
 probably very rare, and perhaps can only occur during a proof.)</p>

 @({
 ***********************************************
 ************ ABORTING from raw Lisp ***********
 ********** (see :DOC raw-lisp-error) **********
 Error:  A live stobj (for stobj ST) was unexpectedly encountered
         when evaluating a call of the function, ST-INIT.
         See :DOC live-stobj-in-proof.
 ***********************************************
 })

 <p>The solution is generally to @(see disable) the @(see
 executable-counterpart) of the offending function.  It may well be that the
 only way to get an unexpected &ldquo;live&rdquo; @(see stobj) is by the use of
 @(tsee swap-stobjs), as suggested by the example shown below (essentially
 provided by Sol Swords) &mdash; which results in a different error message,
 shown below, than the one above.</p>

 <p>First introduce a pair of congruent @(see stobj)s.</p>

 @({
 (defstobj st (fld))
 (defstobj st1 (fld1) :congruent-to st)
 })

 <p>Now define a function that &ldquo;initializes&rdquo; the stobj @('st') by
 creating a new stobj @('st1') and swapping the two (see @(see
 swap-stobjs)).</p>

 @({
 (defun st-init (st)
   (declare (xargs :stobjs (st)))
   (with-local-stobj st1
     (mv-let (st1 st)
       (swap-stobjs st1 st)
       st)))
 })

 <p>Here is a proof attempt that results in a raw Lisp error due to a live
 stobj being introduced by @(tsee swap-stobjs).</p>

 @({
 ACL2 !>(thm (not (equal (st-init '(1)) '(nil))))

 ***********************************************
 Note:  SWAP-STOBJS has been called on stobjs named ST1 and ST,
 where the value of ST1 is a live stobj but the value of ST is not.
 This is an error, as such calls are unsupported; see :DOC swap-stobjs.
 Advanced users may find it helpful to evaluate the form
 (set-debugger-enable :bt)
 to see a backtrace of calls leading to this error;
 see :DOC set-debugger-enable.
   Will attempt to exit the proof in progress;
   otherwise, the next interrupt will abort the proof.
   For an immediate abort see :DOC abort-soft.
 ***********************************************

 The message above might explain the error.  If not, and
 if you didn't cause an explicit interrupt (Control-C),
 then it may help to see :DOC raw-lisp-error.

 To enable breaks into the debugger (also see :DOC acl2-customization):
 (SET-DEBUGGER-ENABLE T)

 Summary
 Form:  ( THM ...)
 Rules: NIL
 Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)

 *** Note: No checkpoints to print. ***

 ACL2 Error [Failure] in ( THM ...):  See :DOC failure.

 ******** FAILED ********
 ACL2 !>
 })

 <p>In fact, that formula is not a theorem!  Through Version  8.6, ACL2
 mistakenly proved this alleged theorem by evaluating the indicated call of
 @('st-init') to obtain an actual Lisp array, because of how ACL2 handles @(see
 stobj)s in Lisp.  But now ACL2 produces the error displayed just above.</p>

 <p>The error is avoided if we @(see disable) the @(see executable-counterpart)
 of the offending function, @('st-init').  Indeed, the following theorem, which
 contradicts the false claim above and disables the offending
 executable-counterpart, shows that the logical value of @('(st-init '(1))') is
 indeed @(''(nil)').</p>

 @({
 (thm (equal (st-init '(1)) '(nil))
      :hints(("Goal" :in-theory (disable (:e st-init)))))
 })")

(defxdoc local
  :parents (events)
  :short "Hiding an event in an encapsulation or book"
  :long "@({
  Examples:
  (local (defthm hack1
           (implies (and (acl2-numberp x)
                         (acl2-numberp y)
                         (equal (* x y) 1))
                    (equal y (/ x)))))

  (local (defun double-naturals-induction (a b)
           (cond ((and (integerp a) (integerp b) (< 0 a) (< 0 b))
                  (double-naturals-induction (1- a) (1- b)))
                 (t (list a b)))))

  General Form:
  (local ev)
 })

 <p>where @('ev') is an event form.  If the current default @(see defun-mode)
 (see @(see default-defun-mode)) is @(':')@(tsee logic) and @(tsee
 ld-skip-proofsp) is @('nil') or @('t'), then @('(local ev)') is equivalent to
 @('ev').  But if the current default @(see defun-mode) is @(':')@(tsee
 program) or if @(tsee ld-skip-proofsp) is @(''')@(tsee include-book), then
 @('(local ev)') is a @('no-op').  Thus, if such forms are in the event list of
 an @(tsee encapsulate) event or in a book, they are processed when the
 encapsulation or book is checked for admissibility in @(':')@(tsee logic) mode
 but are skipped when extending the host @(see world).  Such @(see events) are
 thus considered ``local'' to the verification of the encapsulation or book.
 The non-local @(see events) are the ones ``exported'' by the encapsulation or
 book.  See @(see encapsulate) for a thorough discussion.  Also see @(see
 local-incompatibility) for a discussion of a commonly encountered problem with
 such event hiding: you can't make an event local if its presence is required
 to make sense of a non-local one.</p>

 <p>Note that @(see events) that change the default @(see defun-mode), and in
 fact any @(see events) that set the @(tsee acl2-defaults-table), are
 disallowed inside the scope of @('local').  See @(see
 embedded-event-form).</p>")

(defxdoc local-incompatibility
  :parents (miscellaneous)
  :short "When non-local @(see events) won't replay in isolation"
  :long "<p>Sometimes a ``@(tsee local) incompatibility'' is reported while
 attempting to embed some @(see events), as in an @(tsee encapsulate) or @(tsee
 include-book).  This is generally due to the use of a locally defined name in
 a non-local event or the failure to make a witnessing definition @(tsee
 local).  (But see the Remark at the end of this topic about a related issue
 with guard-checking.)</p>

 <p>@(tsee Local) incompatibilities may be detected while trying to execute the
 strictly non-@(see local) @(see events) of an @(tsee encapsulate) or @(tsee
 certify-book) call.  For example, @('encapsulate') operates by first executing
 all the @(see events) (local and non-local) with @(tsee ld-skip-proofsp)
 @('nil'), to confirm that they are all admissible.  Then it attempts merely to
 assume the non-local ones to create the desired theory, by executing the @(see
 events) with @(tsee ld-skip-proofsp) set to @(''include-book').
 @('Certify-book') does something similar, so that when @(tsee include-book)
 assumes the non-local events in the book, we are confident that the previously
 successful certification has performed the necessary admissibility check.</p>

 <p>How can a sequence of @(see events) admitted with @(tsee ld-skip-proofsp)
 @('nil') fail when @(tsee ld-skip-proofsp) is @(''include-book')?  The key
 observation is that in the latter case only the non-local @(see events) are
 processed.  The @(tsee local) ones are skipped and so the non-local ones must
 not depend upon them.</p>

 <p>Two typical mistakes are suggested by the detection of a @(tsee local)
 incompatibility: (1) a locally defined function or macro was used in a
 non-@(tsee local) event (and, in the case of @(tsee encapsulate), was not
 included among the @(see signature)s) and (2) the witnessing definition of a
 function that was included among the @(see signature)s of an @(tsee
 encapsulate) was not made @(tsee local).</p>

 <p>An example of mistake (1) would be to include among your @(see
 encapsulate)d @(see events) both a local definition of @('f') and a non-local
 theorem about @('f'), for example as follows.</p>

 @({
 (encapsulate ()
   (local (defun f (x) x))
   (defun g (x) x)

   (defthm f-is-g (equal (f x) (g x)))
   )
 })

 <p>In this case, either the @(tsee defthm) should be made @(tsee local) or, if
 we want to export the @('defthm'), then the @(tsee defun) of @('f') should be
 made non-local.  Similar analysis holds if the events in the @('encapsulate')
 call above are instead in a book.</p>

 <p>An example of mistake (2) would be to include @('((fn *) => *)') among your
 @(see signature)s and then to write @('(defun fn (x) ...)') in your @(see
 events), instead of @('(local (defun fn ...))'), as shown in the example
 below.  In essence, this is an error because @('fn') is exported twice: once
 by the signature and once by the @('defun').</p>

 @({
 (encapsulate
   ( ((fn *) => *) )

   (defun fn (x) x)
   )
 })

 <p>One subtle aspect of @(tsee encapsulate) is that if you constrain any
 member of a mutually recursive clique you must define the entire clique
 locally and then you must constrain those members of it you want axiomatized
 non-locally.</p>

 <p>Errors due to @(tsee local) incompatibility should never occur in the
 inclusion of a fully certified book.  Certification ensures against it.
 Therefore, if @(tsee include-book) reports an incompatibility, we claim that
 earlier in the processing of the @(tsee include-book) a warning was printed
 advising you that some book was uncertified.  If this is not the case &mdash;
 if @(tsee include-book) reports an incompatibility and there has been no prior
 warning about lack of certification &mdash; please report it to the ACL2
 implementors.</p>

 <p>When a @(tsee local) incompatibility is detected during the second pass of
 an @(tsee encapsulate) or @(tsee certify-book), the logical @(see world) is
 restored to what it was immediately before that call was evaluated.</p>

 <p>Note that for @('certify-book'), local incompatibility could be caused by
 an event that is local either in the certification world (see @(see
 portcullis)) or in the book itself.  ACL2 checks during @('certify-book') for
 local incompatibility by rolling back the world &mdash; back through the first
 portcullis command that generates a local event, or if there is none, then
 back through the first local event in the book (with the general exception of
 those inside an @('encapsulate'), but see final Remark below) &mdash; and then
 including the book.  But all that is skipped in the absence of either kind of
 local event.</p>

 <p>See @(see fast-cert) for a way to skip the local incompatibility check,
 although that may compromise soundness.</p>

 <p>Here is a subtle example of @(tsee local) incompatibility.  The problem is
 that in order for @('foo-type-prescription') to be admitted using the
 specified @(':typed-term') @('(foo x)'), the conclusion @('(my-natp (foo x))')
 depends on @('my-natp') being a @(see compound-recognizer).  This is fine on
 the first pass of the @(tsee encapsulate), during which lemma @('my-natp-cr')
 is admitted.  But @('my-natp-cr') is skipped on the second pass because it is
 marked @(tsee local), and this causes @('foo-type-prescription') to fail on
 the second pass.</p>

 @({
  (defun my-natp (x)
    (declare (xargs :guard t))
    (and (integerp x)
         (<= 0 x)))

  (defun foo (x)
    (nfix x))

  (encapsulate
   ()
   (local (defthm my-natp-cr
            (equal (my-natp x)
                   (and (integerp x)
                        (<= 0 x)))
            :rule-classes :compound-recognizer))
   (defthm foo-type-prescription
     (my-natp (foo x))
     :hints (("Goal" :in-theory (enable foo)))
     :rule-classes ((:type-prescription :typed-term (foo x)))))
 })

 <p><b>Remark</b>.  We conclude by remarking that for ``local incompatibility''
 in the case of @('certify-book'), the notion of ``local'' is a bit more
 comprehensive than the name suggests, in that it can involve @(see
 guard)-checking in the following situation.  For example, in a fresh ACL2
 session evaluate the @(see command) @('(set-guard-checking :none)') followed
 by @('(table foo 0 (car 3))').  Then any attempt to certify a book should
 fail, since subsequent inclusion of that book would fail with a @(see guard)
 violation; that's because the @('set-guard-checking') call was not saved in
 the @(see certificate) file, hence was not evaluated when evaluating @('(car
 3)') while attempting to include the book.</p>

 <p>The example above may be helpful while reading the following general
 explanation of how local incompatibility incorporates the setting of
 guard-checking.  Suppose you are evaluating @(see command)s directly in the
 top-level read-eval-print loop.  One of those commands might be a call of
 @(tsee set-guard-checking) that weakens guard-checking from its default
 behavior, i.e., @('(set-guard-checking VAL)') where @('VAL') is other than
 @('t'), @(':nowarn'), or @(':all').  This command does not change the logical
 @(see world), so it will not be part of the book's @(see portcullis) commands.
 In that sense, it is like a @(see local) portcullis command.  ACL2 notices
 this case and insists that any portcullis event evaluated with guard-checking
 that is weaker than the default must be rolled back during the check for local
 incompatibilities.</p>")

(defxdoc logand
  :parents (numbers acl2-built-ins)
  :short "Bitwise logical `and' of zero or more integers"
  :long "<p>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
 @('(the integer x)').</p>

 <p>The @(see guard) for @('binary-logand') requires its arguments to be
 integers.  @('Logand') is defined in Common Lisp.  See any Common Lisp
 documentation for more information.</p>

 @(def logand)
 @(def binary-logand)")

(defxdoc logandc1
  :parents (numbers acl2-built-ins)
  :short "Bitwise logical `and' of two ints, complementing the first"
  :long "<p>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.</p>

 <p>The @(see guard) for @('logandc1') requires its arguments to be integers.
 @('Logandc1') is defined in Common Lisp.  See any Common Lisp documentation
 for more information.</p>

 @(def logandc1)")

(defxdoc logandc2
  :parents (numbers acl2-built-ins)
  :short "Bitwise logical `and' of two ints, complementing the second"
  :long "<p>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.</p>

 <p>The @(see guard) for @('logandc2') requires its arguments to be integers.
 @('Logandc2') is defined in Common Lisp.  See any Common Lisp documentation
 for more information.</p>

 @(def logandc2)")

(defxdoc logbitp
  :parents (numbers acl2-built-ins)
  :short "The @('i')th bit of an integer"
  :long "<p>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 @('i')th
 bit is @('1') in the two's complement representation of @('j').</p>

 <p>@('(Logbitp i j)') has a @(see guard) that @('i') is a nonnegative integer
 and @('j') is an integer.</p>

 <p>@('Logbitp') is a Common Lisp function.  See any Common Lisp documentation
 for more information.</p>

 @(def logbitp)")

(defxdoc logcount
  :parents (numbers acl2-built-ins)
  :short "Number of ``on'' bits in a two's complement number"
  :long "<p>@('(Logcount x)') is the number of ``on'' bits in the two's
 complement representation of @('x').</p>

 <p>@('(Logcount x)') has a @(see guard) of @('(integerp x)').</p>

 <p>@('Logcount') is a Common Lisp function.  See any Common Lisp documentation
 for more information.</p>

 @(def logcount)")

(defxdoc logeqv
  :parents (numbers acl2-built-ins)
  :short "Bitwise logical equivalence of zero or more integers"
  :long "<p>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
 @('(the integer x)').</p>

 <p>The @(see guard) for @('binary-logeqv') requires its arguments to be
 integers.  @('Logeqv') is defined in Common Lisp.  See any Common Lisp
 documentation for more information.</p>

 @(def logeqv)
 @(def binary-logeqv)")

(defxdoc logic
  :parents (defun-mode)
  :short "To set the default @(see defun-mode) to @(':logic')"
  :long "@({
  Example:
  ACL2 p!>:logic
  ACL2 !>
 })

 <p>Typing the keyword @(':logic') sets the default @(see defun-mode) to
 @(':logic').</p>

 <p>Functions defined in @(':logic') mode are logically defined.  See @(see
 defun-mode).</p>

 <p>Note: This is an event!  It does not print the usual event @(see summary)
 but nevertheless changes the ACL2 logical @(see world) and is so recorded.</p>

 <p>See @(see defun-mode) for a discussion of the @(see defun-mode)s available
 and what their effects on the logic are.  See @(see default-defun-mode) for a
 discussion of how the default @(see defun-mode) is used.  This event is
 equivalent to @('(table acl2-defaults-table :defun-mode :logic)'), and hence
 is @(tsee local) to any @(see books) and @(tsee encapsulate) @(see events) in
 which it occurs. See @(see acl2-defaults-table).</p>

 <p>Recall that the top-level form @(':logic') is equivalent to @('(logic)');
 see @(see keyword-commands).  Thus, to change the default @(see defun-mode) to
 @(':logic') in a book, use @('(logic)'), which is an embedded event form,
 rather than @(':logic'), which is not a legal form for @(see books).  See
 @(see embedded-event-form).</p>")

(defxdoc logic-fns-list-listp
  :parents (termp acl2-built-ins)
  :short "Recognizer for when a given list of lists of @(see term)s calls only
 @(':')@(tsee logic)-mode function symbols"
  :long "<p>For a list @('x') of lists of @(see term)s in @(see world)
 @('wrld'), @('(logic-fns-list-listp x wrld)') is true if and only if every
 function symbol called in @('x') is in @(':')@(tsee logic) mode in @('wrld').
 Unlike @(tsee logic-term-list-listp), @('logic-fns-list-listp') does not check
 that @('x') is a list of lists of terms; rather, @('logic-fns-list-listp')
 should only be applied to such lists.  See @(tsee defun-mode-lambdas) for some
 clarifications of how @(':program') mode functions are allowed in certain
 @(':logic') mode terms.</p>

 @(def logic-fns-list-listp)")

(defxdoc logic-fns-listp
  :parents (termp acl2-built-ins)
  :short "Recognizer for when a given list of @(see term)s calls only
 @(':')@(tsee logic)-mode function symbols"
  :long "<p>For a list @('x') of @(see term)s in @(see world) @('wrld'),
 @('(logic-fns-listp x wrld)') is true if and only if every function symbol
 called in @('x') is in @(':')@(tsee logic) mode in @('wrld').  Unlike @(tsee
 logic-term-listp), @('logic-fns-listp') does not check that @('x') is a list
 of terms; rather, @('logic-fns-listp') should only be applied to such lists.
 See @(tsee defun-mode-lambdas) for some clarifications of how @(':program')
 mode functions are allowed in certain @(':logic') mode terms.</p>

 @(def logic-fns-listp)")

(defxdoc logic-fnsp
  :parents (termp acl2-built-ins)
  :short "Recognizer for when a given @(see term) calls only @(':')@(tsee
 logic)-mode function symbols"
  :long "<p>For a @(see term) @('x') in @(see world) @('wrld'), @('(logic-fnsp
 x wrld)') is true if and only if every function symbol called in @('x') is in
 @(':')@(tsee logic) mode in @('wrld').  Unlike @(tsee logic-termp),
 @('logic-fnsp') does not check that @('x') is a term; rather, @('logic-fnsp')
 should only be applied to terms.  See @(tsee defun-mode-lambdas) for some
 clarifications of how @(':program') mode functions are allowed in certain
 @(':logic') mode terms.</p>

 @(def logic-fnsp)")

(defxdoc logic-knowledge-taken-for-granted
  :parents (introduction-to-the-theorem-prover)
  :short "Background knowledge in ACL2 logic for theorem prover tutorial"
  :long "<p>You might think that in order to use the theorem prover you have to
 know the mathematical logic supported by ACL2.  But you need to know a lot
 less about it than you might think.</p>

 <p>Technically, a theorem is a formula that can be derived from axioms by
 using rules of inference.  Thus, to do a proof you have to know (a) the syntax
 of formulas, (b) the axioms, and (c) the rules of inference.  Traditionally,
 these things are spelled out in excruciating detail in treatments of
 mathematical logic &mdash; and for good reason.</p>

 <p>The whole point of proving theorems is that it is a way to determine that a
 formula is ``always true'' (under some model of the axioms).  By ``always
 true'' we actually mean what logicians mean when they say the formula is
 <i>valid</i>: true in the model, for all possible values of the variables.
 Here by ``model of the axioms'' we mean an understanding of the meaning of the
 various function symbols so that the axioms are true for all values of the
 variables.  If the variables in your conjecture can take on an infinite number
 of values, proof is often the <b>only</b> way to determine that a conjecture
 is ``always true.''  So if proof is being used to determine that a
 questionable formula is always true the proof must be carried out flawlessly.
 Thus, the (a) syntax, (b) axioms, and (c) rules of inference must be described
 precisely and followed to the letter.</p>

 <p>But formal mathematical logic was invented to explain how people reason.
 To the extent that logic mimics human reasoning, proofs can be seen as just
 extremely carefully crafted arguments.  Given that ACL2 is responsible for
 following the rules ``to the letter,'' your main job is ``explain'' the big
 leaps.</p>

 <p>To use the theorem prover you must understand (a) the syntax, because you
 must be able to write formulas flawlessly.  But you don't have to know (b) the
 axioms and (c) the rules of inference at nearly the same level of precision,
 as long as you understand the basic structure and language of proofs.</p>

 <p>Below is part of a proof of a certain theorem.  You ought to be able to
 understand the following.  Since what we describe is a proof of one case of
 the formula, we hope that you're <i>convinced</i> that the formula holds for
 that case.</p>

 <p>Read this and follow the links to confirm that you understand what happens.
 Be sure to then use your browser's <b>Back Button</b> to return to this page
 and continue.</p>

 <p><b>An Annotated Proof of</b></p>

 @({
  (implies (true-listp z)
           (equal (rev (rev z)) z))
 })

 <p>``We will prove that reversing the reverse of a @('true-listp') yields the
 original list.  The formula stating this is above.  We will prove it by <see
 topic='@(url
 LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-INDUCTIVE-PROOF)'>induction</see> on the
 list structure of @('z').</p>

 <p>The <see topic='@(url LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-BASE-CASE)'>base
 case</see> of the induction is:</p>

 @({
  (implies (endp z)
           (implies (true-listp z)
                    (equal (rev (rev z)) z))).
 })

 <p>This formula is equivalent, by <see topic='@(url
 LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-PROPOSITIONAL-CALCULUS)'>propositional
 calculus</see>, to</p>

 @({
  (implies (and (endp z)
                (true-listp z))
           (equal (rev (rev z)) z))
 })

 <p><see topic='@(url
 LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-REWRITING)'>Rewriting</see> with the
 definition of @('endp') produces:</p>

 @({
  (implies (and (not (consp z))
                (true-listp z))
           (equal (rev (rev z)) z))
 })

 <p><see topic='@(url
 LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-REWRITING-REPEATEDLY)'>Rewriting
 repeatedly</see> starting with the definition of @('true-listp') produces:</p>

 @({
  (implies (and (not (consp z))
                (equal z nil))
           (equal (rev (rev z)) z))
 })

 <p>Then using the second <i>hypothesis</i>, just <see topic='@(url
 LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-EQUALS-FOR-EQUALS)'>substituting equals for
 equals</see>, we get</p>

 @({
  (implies (and (not (consp z))
                (equal z nil))
           (equal (rev (rev nil)) nil))
 })

 <p>Since the <i>conclusion</i> involves no variables, we can <see topic='@(url
 LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-EVALUATION)'>evaluate</see> it, getting</p>

 @({
  (implies (and (not (consp z))
                (equal z nil))
           T)
 })

 <p>But this is an <see topic='@(url
 LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-INSTANCE)'>instance</see> of the <see
 topic='@(url
 LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-PROPOSITIONAL-CALCULUS)'>tautology</see>
 @('(implies p T)').  Thus, the base case is proved.''</p>

 <p>Now it is time for a little quiz.  There are just three questions.</p>

 <p><b>Q1</b>: The case above was the Base Case of an inductive proof of</p>

 @({
  (implies (true-listp z)
           (equal (rev (rev z)) z))
 })

 <p>in which we did induction on the structure of the linear list @('z').  What
 is the Induction Step?  That is, what do you have to prove besides the Base
 Case to complete this inductive proof?</p>

 <p>Below are four commonly given answers; choose one.  Then look <see
 topic='@(url LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-Q1-ANSWER)'>here</see> to find
 out if you're right.</p>

 <code>
 <i>Induction Step -- Choice (i)</i>:
 (implies (not (endp z))
          (implies (true-listp z)
                   (equal (rev (rev z)) z)))

 <i>Induction Step -- Choice (ii)</i>:
 (implies (true-listp (cdr z))
          (equal (rev (rev (cdr z))) (cdr z)))

 <i>Induction Step -- Choice (iii)</i>:
 (implies (and (not (endp z))
               (equal (rev (rev (cdr x))) (cdr x)))
          (implies (true-listp z)
                   (equal (rev (rev z)) z)))

 <i>Induction Step -- Choice (iv)</i>:
 (implies (and (not (endp z))
               (implies (true-listp (cdr z))
                        (equal (rev (rev (cdr z))) (cdr z))))
          (implies (true-listp z)
                   (equal (rev (rev z)) z)))
 </code>

 <p><b>Q2</b>: To prove the Induction Step we must prove one or more of the
 goals below.</p>

 <p>Which combinations are sufficient to imply the Induction Step?  Decide what
 is required and then look <see topic='@(url
 LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-Q2-ANSWER)'>here</see> to find out if you're
 right.  To help you, the Induction Step is of the form:</p>

 <code>
 <i>Induction Step</i>:
 (implies (and <i>c</i>
               (implies <i>p'</i> <i>q'</i>))
          (implies <i>p</i> <i>q</i>))
 </code>

 <p>and beside each candidate subgoal we show its structure in those terms.</p>

 <code>
 <i>Subgoal (i)</i>:
 (implies (and (not (endp z))                        ; (implies (and <i>c</i>
               (true-listp z))                       ;               <i>p</i>)
          (true-listp (cdr z)))                      ;          <i>p'</i>)

 <i>Subgoal (ii)</i>:
 (implies (and (not (endp z))                        ; (implies (and <i>c</i>
               (true-listp z)                        ;               <i>p</i>
               (equal (rev (rev (cdr z))) (cdr z)))  ;               <i>q'</i>)
          (equal (rev (rev z)) z))                   ;          <i>q</i>)

 <i>Subgoal (iii)</i>:
 (implies (and (not (endp z))                        ; (implies (and <i>c</i>
               (equal (rev (rev (cdr z))) (cdr z)))  ;               <i>q'</i>)
          (equal (rev (rev z)) z))                   ;          <i>q</i>)

 <i>Subgoal (iv)</i>:
 (implies (and (not (endp z))                        ; (implies (and <i>c</i>
               (true-listp (cdr z))                  ;               <i>p'</i>
               (equal (rev (rev (cdr z))) (cdr z)))  ;               <i>q'</i>)
          (equal (rev (rev z)) z))                   ;          <i>q</i>)
 </code>

 <p><b>Q3</b>: Suppose you know the theorem</p>

 <code>
 <i>Theorem</i>:
 (implies (p (f x))
          (equal (g (h x))
                 x))
 </code>

 <p>and you wish to rewrite the target @('(g (h a))') to @('a') in</p>

 <code>
 <i>Goal Conjecture</i>:
 (implies (and (q (f a))
               (r a))
          (s (g (h a))))
 </code>

 <p>What must you prove to relieve the hypothesis of <i>Theorem</i>?</p>

 <p>After you've thought about it, look <see topic='@(url
 LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-Q3-ANSWER)'>here</see> for our answer.</p>

 <p><b>End of the Quiz</b></p>

 <p>If this page made sense, you're ready to read the introduction to the
 theorem prover.</p>

 <p>If you are reading this as part of the tutorial introduction to the theorem
 prover, use your browser's <b>Back Button</b> now to return to @(see
 introduction-to-the-theorem-prover).</p>")

(defxdoc logic-knowledge-taken-for-granted-base-case
  :parents (introduction-to-the-theorem-prover)
  :short "A brief explanation of base cases"
  :long "<p>According to the sentence, the conjecture being proved is
 ``reversing the reverse of a @('true-listp') yields the original list.''  The
 formula corresponding to this conjecture is:</p>

 @({
  (implies (true-listp z)
           (equal (rev (rev z)) z)).
 })

 <p>We're also told that this is an inductive proof.  Evidently we're doing an
 induction on the structure of the list @('z').  Then the <i>Base Case</i> is
 the formula:</p>

 @({
  (implies (endp z)
           (implies (true-listp z)
                    (equal (rev (rev z)) z))).
 })

 <p>Now use your browser's <b>Back Button</b> to return to the example proof in
 @(see logic-knowledge-taken-for-granted).</p>")

(defxdoc logic-knowledge-taken-for-granted-equals-for-equals
  :parents (introduction-to-the-theorem-prover)
  :short "Substitution of equals for equals"
  :long "<p>Anytime you have an equality hypothesis relating two terms,
  e.g.,</p>

 <code>
 (equal <i>lhs</i> <i>rhs</i>)
 </code>

 <p>it is legal to substitute one for the other anyplace else in the formula.
 Doing so does not change the truth value of the formula.</p>

 <p>You can use a <i>negated equality</i> this way <i>provided</i> it appears
 in the conclusion.  For example, it is ok to transform</p>

 @({
  (implies (true-listp x)
           (not (equal x 23)))
 })

 <p>to</p>

 @({
  (implies (true-listp 23)
           (not (equal x 23)))
 })

 <p>by substitutions of equals for equals.  That is because, by <see
 topic='@(url
 LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-PROPOSITIONAL-CALCULUS)'>propositional
 calculus</see>, we could rearrange the formulas into their
 <i>contrapositive</i> forms:</p>

 @({
  (implies (equal x 23)
           (not (true-listp x)))
 })

 <p>and</p>

 @({
  (implies (equal x 23)
           (not (true-listp 23)))
 })

 <p>and see the equality as a hypothesis and the substitution of @('23') for
 @('x') as sensible.</p>

 <p>Sometimes people speak loosely and say ``substitution of equals for
 equals'' when they really mean ``substitutions of equivalents for
 equivalents.''  Equality, as tested by @('EQUAL'), is only one example of an
 equivalence relation.  The next most common is propositional equivalence, as
 tested by @('IFF').  You can use propositional equivalence hypotheses to
 substitute one side for the other <i>provided</i> the target term occurs in a
 propositional place, as discussed at the bottom of <see topic='@(url
 LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-PROPOSITIONAL-CALCULUS)'>propositional
 calculus</see>.</p>

 <p>Now use your browser's <b>Back Button</b> to return to the example proof in
 @(see logic-knowledge-taken-for-granted).</p>")

(defxdoc logic-knowledge-taken-for-granted-evaluation
  :parents (introduction-to-the-theorem-prover)
  :short "Evaluation during proofs"
  :long "<p>Any time you are proving a formula and see a subterm in the formula
 that contains no variables, you can just evaluate the subterm.</p>

 <p>This is familiar from algebra: It is not uncommon to rearrange a
 polynomial to collect all the constants and then add them up:</p>

 @({
  (3x + 2 + 7y + 2)
  =
  (3x + 7y + (2 + 2))
  =
  (3x + 7y + 4).
 })

 <p>That last step is just evaluation.</p>

 <p>It happens often in ACL2 proofs because theorems involve constants and
 defined functions and when those constants ``drift into the maw'' of a
 function, the function call can be eliminated and replaced by a new constant.
 ACL2 does this automatically; you don't have to tell it.  In fact, there are a
 few occasions where you might prefer it <i>not</i> evaluate and those are the
 ones you have to look out for!  They'll be obvious when they happen because
 you'll see a mysterious constant crop up in the proof.</p>

 <p>Evaluation is legal because it is just the repeated use of unconditional
 rewriting to replace definitions by their instantiated bodies until no
 function calls remain.</p>

 <p>Now use your browser's <b>Back Button</b> to return to the example proof in
 @(see logic-knowledge-taken-for-granted).</p>")

(defxdoc logic-knowledge-taken-for-granted-inductive-proof
  :parents (introduction-to-the-theorem-prover)
  :short "A brief explanation of induction"
  :long "<p>We start by showing classical induction on the natural numbers in
 an ACL2 setting before turning to a more general treatment of induction.</p>

 <p><b>Classical Induction on Natural Numbers</b>: Induction is familiar in the
 arithmetic setting.  Let @('(p n)') denote some formula involving the variable
 @('n') (and perhaps some other variables which we don't exhibit).  Then to
 prove @('(p n)'), for all @('n'), by classical induction on the construction
 of the natural numbers, prove each of the following:</p>

 <code>
 <i>Base Case</i>:
 (implies (zp n) (p n))
 </code>

 <code>
 <i>Induction Step</i>:
 (implies (and (not (zp n))
               (p (- n 1)))
          (p n))
 </code>

 <p>The Base Case establishes that @('p') holds for @('0').  In fact, because
 of the definition of @(tsee zp) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>, it
 establishes that @('(p n)') holds when @('n') is @('0') and it holds when
 @('n') is not a natural number.</p>

 <p>The Induction Step establishes that if @('n') is a natural number other
 than @('0'), and if @('p') holds for @('n')-1, then @('p') holds for @('n').
 The hypothesis @('(p (- n 1))') above is called the <i>induction
 hypothesis</i>.</p>

 <p>Note that if the Base Case and Induction Step are valid, then we know @('(p
 n)'), for all @('n').  You can convince yourself of this by picking any object
 and asking ``how do I know @('p') holds for this object?''  For example, @('(p
 -7)'), @('(p 'abc)'), and @('(p 0)') are all established by the Base Case.
 What about @('(p 1)')?  That follows from @('(p 0)'), given the Induction
 Step.  Why?  To prove @('(p 1)') using the Induction Step, you have to
 establish @('(not (zp 1))'), which is true, and @('(p (- 1 1))'), which is
 @('(p 0)'), which is true by the Base Case.  So @('(p 1)') is true.  Similar
 reasoning proves @('(p 2)') from from @('(p 1)'), etc.  Clearly, for every
 natural number other than @('0') we could reason like this to show that @('p')
 holds.  Since the Base Case handled all the objects that are not natural
 numbers, and handled @('0'), we know @('(p n)'), for all @('n').</p>

 <p>There is a duality between recursion and induction that ACL2 exploits.  The
 fact that the Base and Induction steps above are sufficient to prove @('p')
 for all objects is related to the fact that the following recursion defines a
 total, terminating function:</p>

 @({
  (defun nat-recursion (n)
    (if (zp n)
        n
        (nat-recursion (- n 1))))
 })

 <p>When this function is admitted we have to prove that if @('(zp n)') does
 not hold, then @('(- n 1)') is smaller, in some sense, than @('n').  This
 sense of ``smaller'' is determined by some <i>measure</i> of the arguments.
 That measure must return an ordinal (see @(see ordinals) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>),
 but the most common measures return natural numbers, which are among the
 ordinals.  Furthermore, that measure should ensure that the terms in the
 recursive calls are smaller than the formals, i.e., the measure of @('(- n
 1)') must be smaller than the measure of @('n'), when the recursive branches
 are taken.  This sense of ``smaller'' must be <i>well-founded</i>: it must be
 impossible to have an infinitely descending chain of smaller things.  This is
 true of the less-than relation on the ordinals (see @(tsee o<) <see
 topic='ACL2____A_02Tiny_02Warning_02Sign'><icon src='res/tours/twarning.gif'/></see>).
 Well-foundedness means that eventually any recursion must ``bottom out''
 because things can't keep getting smaller forever.</p>

 <p>The recursion in @('nat-recursion') <b>suggests</b> the induction shown
 above: the Base Case is defined by the @('if') branch that does not lead to a
 recursive call.  The Induction Step is defined by the other branch.  The
 induction hypothesis is defined by what we recur on, i.e., @('(- n 1)').  The
 theorems proved when @('nat-recursion') is introduced <i>justify</i> the
 classical induction scheme noted above.</p>

 <p>Every recursively defined ACL2 function suggests a legal induction and vice
 versa.</p>

 <p>Furthermore, every call of a recursively defined function on distinct
 variable symbols also suggests a legal induction: just take the induction
 suggested by the function's recursive definition after renaming the formal
 parameters to be the variables in the call.</p>

 <p>For example, it should be clear that @('(nat-recursion a)') suggests a Base
 Case defined by @('(zp a)'), and induction step defined by @('(not (zp a))')
 and an induction hypothesis about @('(- a 1)').</p>

 <p>Note that the term @('(fact n)') suggests the same classical induction on
 natural numbers shown above, where @('fact') is defined as follows (even
 though we've used the formal parameter @('k') below).</p>

 @({
  (defun fact (k)
    (if (zp k)
        1
        (* k (fact (- k 1)))))
 })

 <p>The induction suggested by a term like @('(fact n)') is insensitive to the
 name of the formal parameter used in the @('defun').</p>

 <p>The induction suggested by a function or term is insensitive to the value
 returned by the function or term.</p>

 <p>It doesn't matter what the function returns in its ``base case'' (e.g.,
 @('1') in @('fact')) or what the function ``does'' to its recursive call
 (e.g., multiply by @('k') in the @('defun') of @('fact')).</p>

 <p>All that matters is (i) how the @('if') structure breaks down the cases on
 @('k'), (ii) which branches lead to recursion, and (iii) what arguments are
 passed to the recursive calls.  Those things determine (i) the case analysis
 of the induction scheme, (ii) which cases are Base Cases and which are
 Induction Steps, and (iii) what the induction hypotheses are.</p>

 <p>For a selection of common inductions schemes in ACL2 (e.g., on the
 structure of natural numbers, lists, and trees and on several variables at
 once, multiple base cases, multiple induction hypotheses, multiple induction
 steps, etc.)  <see topic='@(url EXAMPLE-INDUCTIONS)'>check this
 link</see>.</p>

 <p>Every legal ACL2 induction corresponds to an admissible recursive function
 and vice versa.  Similarly, every legal ACL2 induction corresponds to a call
 of a recursively defined function on distinct variables.</p>

 <p>ACL2 chooses which induction to do by looking at the terms that occur in
 the conjecture.  For many elementary theorems, ACL2 chooses the right
 induction by itself.</p>

 <p>You may occasionally need to tell it what induction to do.  You do that by
 showing it a term that suggests the induction you want.  We'll explain how you
 communicate this to ACL2 later.  If you understand how recursive functions
 suggest inductions, then you know what you need to know to use ACL2.</p>

 <p>The main point of this discussion of induction is familiarize you with the
 basic terms: <i>Base Case</i> (of which there may be several), <i>Induction
 Step</i> (of which there may be several), <i>Induction Hypothesis</i> (of
 which there may be several in each Induction Step), <i>measure</i> and
 <i>well-founded relation</i> <i>justifying</i> an induction, and the induction
 <i>suggested</i> by a term or recursive function definition.  Furthermore,
 every Induction Hypothesis is always an <see topic='@(url
 LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-INSTANCE)'>instance</see> of the conjecture
 being proved: each induction hypothesis is obtained from the conjecture being
 proved by applying a <i>substitution</i> replacing variables by terms.</p>

 <p>If you are reviewing the material taken for granted about logic while
 working your way through the introduction to the theorem prover, please use
 your browser's <b>Back Button</b> to return to the example proof in @(see
 logic-knowledge-taken-for-granted).</p>")

(defxdoc logic-knowledge-taken-for-granted-instance
  :parents (introduction-to-the-theorem-prover)
  :short "A brief explanation of substitution instances"
  :long "<p>Let <i>p</i> and <i>q</i> be terms or formulas (there is no
 difference in ACL2).  Then we say <i>p</i> is an <i>instance</i> or
 <i>substitution instance</i> of <i>q</i> if and only if <i>p</i> can be
 obtained from <i>q</i> by uniformly replacing the variables of <i>q</i> by
 terms.  Sometimes we call <i>p</i> the <i>target</i> and <i>q</i> the
 <i>pattern</i> because by choosing appropriate replacements we can make the
 pattern <i>match</i> many different targets.</p>

 <p>For example, the following <i>target</i> is an instance of the given
 <i>pattern</i>:</p>

 <code>
 <i>target</i>:      (APP (APP (REV A) (REV B)) (REV C))
 <i>pattern</i>:     (APP (APP   x       y    ) (REV z))
 </code>

 <p>The replacement or <i>substitution</i> used in this match of the pattern to
 the target is:</p>

 <code>
 <i>variable in pattern</i>          <i>replacement term</i>
 x                              (REV A)
 y                              (REV B)
 z                              C
 </code>

 <p>Such substitutions are usually written this way in ACL2:</p>

 @({
  ((x  (REV A))
   (y  (REV B))
   (z  C)).
 })

 <p>Please use your browser's <b>Back Button</b> to return to the page that
 mentioned ``instance.''</p>")

(defxdoc logic-knowledge-taken-for-granted-propositional-calculus
  :parents (introduction-to-the-theorem-prover)
  :short "A brief explanation of propositional calculus"
  :long "<p>It is impossible in this short introduction to teach you
 propositional calculus if you don't already know it!</p>

 <p>A typical use of propositional calculus is to observe that</p>

 @({
  (implies (endp z)
           (implies (true-listp z)
                    (equal (rev (rev z)) z)))
 })

 <p>is equivalent to:</p>

 @({
   (implies (and (endp z)
                 (true-listp z))
            (equal (rev (rev z)) z))
 })

 <p>If this is surprising and you know propositional calculus, then the problem
 might be our notation.  We're exploiting the tautology</p>

 <code>
 <i>(p ---&gt; (q ---&gt; r)) &lt;---&gt; ((p &amp; q) ---&gt; r)</i>
 </code>

 <p>where <i>---&gt;</i> and <i>&lt;---&gt;</i> are meant to be the traditional
 arrows denoting logical implication and logical equivalence.</p>

 <p>If you don't know propositional calculus, we'll say just a few things to
 help ease your journey.</p>

 <p>A <i>propositional formula</i>, in ACL2, is any formula written entirely in
 terms of variable symbols, @('T'), @('NIL'), and the propositional functions
 @('AND'), @('OR'), @('NOT'), @('IMPLIES'), and @('IFF').  The ``tautology''
 above in traditional notation is this propositional formula in ACL2:</p>

 @({
  (IFF (IMPLIES P (IMPLIES Q R))
       (IMPLIES (AND P Q) R)).
 })

 <p>If you have a formula like</p>

 <code>
 (implies <i>hyp</i>
          <i>concl</i>)
 </code>

 <p>then we say that formula is an <i>implication</i>, that <i>hyp</i> is the
 <i>hypothesis</i>, and that <i>concl</i> is the conclusion.  If the hypothesis
 is an @('and') expression, as in</p>

 <code>
 (implies (and <i>hyp1</i>
               <i>hyp2</i>
               ...)
          <i>concl</i>)
 </code>

 <p>then we call <i>hyp1</i> is the <i>first hypothesis</i>, <i>hyp2</i> is the
 <i>second hypothesis</i>, etc.</p>

 <p>If a term is of the form</p>

 <code>
 (and <i>term1</i> <i>term2</i> ...)
 </code>

 <p>we say it is a <i>conjunction</i> and that <i>term1</i> is the <i>first
 conjunct</i>, <i>term2</i> is the <i>second conjunct</i>, etc.  We treat an
 @('or')-term analogously but call it a <i>disjunction</i> and its arguments
 are <i>disjuncts</i>.</p>

 <p>A <i>tautology</i> is any propositional formula that can be proved by
 testing it under all combinations of Boolean assignments to its variables.  We
 give an example of such a <i>truth-table proof</i> below, but hasten to add
 that ACL2 does not generally use truth tables to recognize tautologies.  It
 primarily uses @(see normalization) and BDDs to recognize tautologies, which
 can be seen as a mix of symbolic manipulation and case analysis.</p>

 <p>Many tautologies have names, but ACL2 doesn't refer to them by name because
 it derives them from first principles.  We list a few here because we
 sometimes use the names in our documentation; more importantly, you should
 look at these formulas and convince yourself that they're always true for all
 Boolean values of the variables:</p>

 <code>
 <i>Double Negation</i>:
 (iff (not (not p)) p)

 <i>DeMorgan</i>:
 (iff (not (and p q))
      (or (not p) (not q)))

 <i>Distributivity</i>:
 (iff (and p (or q r))
      (or (and p q)
          (and p r)))

 <i>Promotion</i>:
 (iff (implies p (implies q r))
      (implies (and p q) r))

 <i>Implicative Disjunction</i>:
 (iff (implies p q)
      (or (not p) q))

 <i>Contrapositive</i>:
 (iff (implies p q)
      (implies (not q) (not p)))

 <i>Generalized Contrapositive</i>:
 (iff (implies (and p r) q)
      (implies (and p (not q)) (not r)))

 </code>

 <p>There are, of course, many others, even with these same names!  For
 example, there is a dual version of DeMorgan showing how @('not') distributes
 over @('or'), a dual version of Distributivity for @('or') over @('and'),
 etc.</p>

 <p>Dealing with propositional calculus will not generally be a problem for you
 because it is decidable and ACL2 has procedures that decide propositional
 formulas.  However, propositional calculus can lead to exponential explosion
 and can thus explain why ACL2 has ``gone out to lunch.''  In addition,
 sometimes if you are curious as to <i>why</i> ACL2 is working on a certain
 subgoal the reason can be traced back to propositional calculus.</p>

 <p>The most common example of this is that to prove a formula of the form</p>

 @({
  (implies (implies p1 q1)
           (implies p2 q2))
 })

 <p>propositional calculus will convert it to</p>

 @({
  (and (implies (and p2 (not p1)) q2)
       (implies (and p2 q1) q2))
 })

 <p>Many users are surprised that the first conjunct above does not have
 @('q1') as a hypothesis.  If you ever stare at an ACL2 goal and say to
 yourself ``A hypothesis is missing!'' the chances are that propositional
 calculus is ``to blame.''  In particular, if you are trying to prove that
 @('(implies p1 q1)') implies something, you must deal with the case that
 @('(implies p1 q1)') is true because @('p1') is false.  Think about it.</p>

 <p>Now we illustrate the truth table method for deciding tautologies, even
 though that is not what ACL2 generally uses.  Consider the formula called
 Promotion above:</p>

 @({
  (IFF (IMPLIES P (IMPLIES Q R))
       (IMPLIES (AND P Q) R))
 })

 <p>The formula above is a tautology.  It contains three variables, @('P'),
 @('Q'), and @('R'), and so there are 8 combinations of Boolean assignments to
 them.  If we let</p>

 <code>
 <i>formula1</i>:  (IMPLIES P (IMPLIES Q R))
 <i>formula2</i>:  (IMPLIES (AND P Q) R)
 </code>

 <p>then we wish to test the formula @('(IFF ')<i>formula1
 formula2</i>@(')'):</p>

 <code>
 P   Q   R       <i>formula1</i>   <i>formula2</i>   (IFF <i>formula1</i> <i>formula2</i>)
 ---------
 T   T   T            T         T       T
 T   T   NIL          NIL       NIL     T
 T   NIL T            T         T       T
 T   NIL NIL          T         T       T
 NIL T   T            T         T       T
 NIL T   NIL          T         T       T
 NIL NIL T            T         T       T
 NIL NIL NIL          T         T       T
 </code>

 <p>So we see that the formula always returns @('T') and is thus a
 tautology.</p>

 <p>Recall that in the original example at the top of this page we were trying
 to prove the formula</p>

 @({
  (implies (endp z)
           (implies (true-listp z)
                    (equal (rev (rev z)) z)))
 })

 <p>This formula is an <see topic='@(url
 LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-INSTANCE)'>instance</see> of</p>

 @({
  (implies p (implies q r)).
 })

 <p>The substitution required by the match is</p>

 <code>
 <i>sigma</i>:
 ((p    (endp z))
  (q    (true-listp z))
  (r    (equal (rev (rev z)) z)))
 </code>

 <p>Since we know the tautology:</p>

 @({
  (iff (implies p (implies q r))
       (implies (and p q) r)).
 })

 <p>is always true no matter what Boolean values @('p'), @('q'), and @('r')
 have, then we know this instance of it (obtained by applying the substitution
 <i>sigma</i> above) is always true:</p>

 <code>
 (iff (implies (endp z)                            <i>formula1'</i>
               (implies (true-listp z)
                        (equal (rev (rev z)) z)))
      (implies (and (endp z)                       <i>formula2'</i>
                    (true-listp z))
               (equal (rev (rev z)) z))).
 </code>

 <p>Thus, if we're trying to prove <i>formula1'</i> it is permitted to try to
 prove <i>formula2'</i> instead, because they return the same truthvalue.</p>

 <p>This sketch of propositional reasoning in ACL2 is a little suspect because
 we didn't address the possibility that the substitution might replace the
 propositional variables by non-propositional terms.  But the tautology was
 verified only on Boolean values for those variables.  This actually works out
 because in ACL2 all propositional testing is done against @('nil') and any
 non-@('nil') value, including @('t'), is as good as another.  However, the
 tautology allows us to replace one formula by the other only in contexts in
 which we just care about propositional truth, i.e., whether the formula is
 @('nil') or not.  When we prove a formula in ACL2 we are really establishing
 that it never returns @('nil'), i.e., no matter what the values of the
 variables, the value of the formula is non-@('nil').</p>

 <p>A very simple example of this is with Double Negation.</p>

 @({
  (iff (not (not p)) p)
 })

 <p>is a tautology.  This means that if we were trying to prove</p>

 @({
  (implies (not (not p)) ...)
 })

 <p>we could transform it to</p>

 @({
  (implies p ...).
 })

 <p>But if we were trying to prove:</p>

 @({
  (equal (not (not p)) p)
 })

 <p>we could not prove it by using Double Negation!  The formula above claims
 that @('(not (not p))') and @('p') have identical values.  They do not!  For
 example, @('(not (not 3))') is @('t'), not @('3').  However, @('(not (not
 3))') and @('t') are propositionally equivalent (i.e., satisfy @('iff'))
 because one is as good as the other in a test.  <i>That</i> is what Double
 Negation says.</p>

 <p>As long as you only use propositional formulas in propositional places this
 aspect of ACL2 should not affect you.</p>

 <p>Now please use your browser's <b>Back Button</b> to return to the example
 proof in @(see logic-knowledge-taken-for-granted).</p>")

(defxdoc logic-knowledge-taken-for-granted-q1-answer
  :parents (introduction-to-the-theorem-prover)
  :short "The inductive step of the @('rev-rev') proof — Answer to Question 1"
  :long "<p>The correct answer to Question 1 in @(see
 logic-knowledge-taken-for-granted) is <i>Choice (iv)</i>.</p>

 <p>The Induction Step of the inductive proof of</p>

 @({
  (implies (true-listp z)
           (equal (rev (rev z)) z))
 })

 <p>for an induction on the linear list @('z') is:</p>

 <code>
 <i>Induction Step</i>:
 (implies (and (not (endp z))
               (implies (true-listp (cdr z))
                        (equal (rev (rev (cdr z))) (cdr z))))
          (implies (true-listp z)
                   (equal (rev (rev z)) z)))
 </code>

 <p>The second hypothesis above is the <i>induction hypothesis</i>.  The
 conclusion above is the formula we are trying to prove.  Each induction
 hypothesis is <i>always</i> an <see topic='@(url
 LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-INSTANCE)'>instance</see> of the formula
 being proved, i.e., it is obtained from the formula being proved by uniformly
 replacing the variables in the formula with terms.  Notice how the induction
 hypothesis above is the same as the induction conclusion, except that all the
 @('z')s have been replaced by @('(cdr z)').</p>

 <p>If you thought the right answer was</p>

 <code>
 <i>Induction Step -- Choice (i)</i>:
 (implies (not (endp z))
          (implies (true-listp z)
                   (equal (rev (rev z)) z)))
 </code>

 <p>then perhaps you didn't understand that we're doing an inductive proof.
 Certainly if you prove the Base Case already discussed and you prove <i>Choice
 (i)</i> above, then you will have proved the goal conjecture, but you would
 have done it by simple case analysis: prove it when @('(endp z)') and prove it
 when @('(not (endp z))').  While logically valid, you probably can't prove
 <i>Choice (i)</i> directly because you have no induction hypothesis to work
 with.</p>

 <p>If you thought the right answer was:</p>

 <code>
 <i>Induction Step -- Choice (ii)</i>:
 (implies (true-listp (cdr z))
          (equal (rev (rev (cdr z))) (cdr z)))
 </code>

 <p>then perhaps you misunderstand the difference between the <i>Induction
 Step</i> and the <i>Induction Hypothesis</i>.  The Induction <i>Step</i> is
 the ``other half'' of the main proof, balancing the Base Case.  The Induction
 <i>Hypothesis</i> is just a hypothesis you get to use during the Induction
 Step.  The question Q1 asked what is the Induction Step.</p>

 <p>If you thought the right answer was:</p>

 <code>
 <i>Induction Step -- Choice (iii)</i>:
 (implies (and (not (endp z))
               (equal (rev (rev (cdr x))) (cdr x))) ; <i>``induction hyp''</i>
          (implies (true-listp z)
                   (equal (rev (rev z)) z)))
 </code>

 <p>then you are making the most common mistake newcomers make to induction.
 You are giving yourself an ``induction hypothesis'' that is not an instance of
 the conjecture you're proving.  This alleged induction hypothesis says that
 @('(rev (rev (cdr x)))') is @('(cdr x)'), whereas the correct induction
 hypothesis says those two terms are equal <i>if</i> @('(true-listp (cdr x))').
 This alleged induction hypothesis is a stronger claim than we're trying to
 prove.  It turns out that by making this mistake you can ``prove'' conjectures
 that are not always true!  Remember: the induction hypothesis is always an
 instance of the conjecture you're proving, not just some piece of it.  Of
 course, ACL2 ``knows'' this and will never make this mistake.  But we remind
 you of it because there may be times when you intuit a different hypothesis
 and don't understand why ACL2 doesn't use it.</p>

 <p>If this doesn't make sense, perhaps you should read about <see topic='@(url
 LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-INDUCTIVE-PROOF)'>induction</see> again.</p>

 <p>When you understand why <i>Choice (iv)</i> is the correct answer, use your
 browser's <b>Back Button</b> to return to @(see
 logic-knowledge-taken-for-granted) and go to question Q2.</p>")

(defxdoc logic-knowledge-taken-for-granted-q2-answer
  :parents (introduction-to-the-theorem-prover)
  :short "The inductive step of the @('rev-rev') proof — Answer to Question 2"
  :long "<p>The correct answer to Question 2 in @(see
 logic-knowledge-taken-for-granted) is <i>Subgoal (i)</i> plus any one of the
 other other three.  For your reference, the four choices were:</p>

 <code>
 <i>Subgoal (i)</i>:
 (implies (and (not (endp z))
               (true-listp z))
          (true-listp (cdr z)))

 <i>Subgoal (ii)</i>:
 (implies (and (not (endp z))
               (true-listp z)
               (equal (rev (rev (cdr z))) (cdr z)))
          (equal (rev (rev z)) z))

 <i>Subgoal (iii)</i>:
 (implies (and (not (endp z))
               (equal (rev (rev (cdr z))) (cdr z)))
          (equal (rev (rev z)) z))

 <i>Subgoal (iv)</i>:
 (implies (and (not (endp z))
               (true-listp (cdr z))
               (equal (rev (rev (cdr z))) (cdr z)))
          (equal (rev (rev z)) z))
 </code>

 <p>In particular, it is wrong to think the Induction Step of the proof of</p>

 @({
  (implies (true-listp z)
           (equal (rev (rev z)) z))
 })

 <p>can be established by proving just <i>Subgoal (ii)</i>, <i>Subgoal
 (iii)</i>, <i>Subgoal (iv)</i>, or combinations of those three.  You must also
 prove <i>Subgoal (i)</i> or something like it!</p>

 <p>The Inductive Step for the conjecture above is</p>

 <code>
 <i>Induction Step</i>:
 (implies (and (not (endp z))
               ; <i>Induction Hypothesis</i>:
               (implies (true-listp (cdr z))
                        (equal (rev (rev (cdr z))) (cdr z))))
          ; <i>Induction Conclusion</i>:
          (implies (true-listp z)
                   (equal (rev (rev z)) z)))
 </code>

 <p>Note that the Inductive Hypothesis is an implication:</p>

 @({
  (implies (true-listp (cdr z))
           (equal (rev (rev (cdr z))) (cdr z)))
 })

 <p>This hypothesis can be true two different ways.  The ``normal'' way &mdash;
 the way everybody remembers &mdash; is that @('(true-listp (cdr z))') is true
 and thus @('(equal (rev (rev (cdr z))) (cdr z))') is true.  But the way many
 people forget is that @('(true-listp (cdr z))') is false.  You must prove the
 Induction Step even in this ``forgettable'' case.</p>

 <p>In this case, the Induction Step simplifies to</p>

 <code>
 <i>Induction Step</i>:
 (implies (and (not (endp z))
               (not (true-listp (cdr z))))
          (implies (true-listp z)
                   (equal (rev (rev z)) z)))
 </code>

 <p>By Promotion (see the list of tautologies in our discussion of <see
 topic='@(url
 LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-PROPOSITIONAL-CALCULUS)'>propositional
 calculus</see>) this is</p>

 <code>
 <i>Induction Step'</i>:
 (implies (and (not (endp z))
               (not (true-listp (cdr z)))
               (true-listp z))
          (equal (rev (rev z)) z))
 </code>

 <p>Using the Contrapositive and rearranging the order of the hypotheses (see
 <see topic='@(url
 LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-PROPOSITIONAL-CALCULUS)'>propositional
 calculus</see> again), this is</p>

 <code>
 <i>Induction Step''</i>:
 (implies (and (not (endp z))
               (true-listp z)
               (not (equal (rev (rev z)) z)))
          (true-listp (cdr z)))
 </code>

 <p>Notice that <i>Subgoal (i)</i> implies <i>Induction Step''</i>:</p>

 <code>
 <i>Subgoal (i)</i>:
 (implies (and (not (endp z))
               (truelistp z))
          (truelistp (cdr z)))
 </code>

 <p>Every inductive proof of an implication raises a case like this.  If we
 denote the conjecture @('(implies p q)') as @('p ---> q'), then the Induction
 Step will look like this:</p>

 @({
    ( c  &  (p'  --->  q'))
  --->
    (p ---> q)
 })

 <p>where @('c') is the test that determines the inductive step, (e.g., @('(not
 (endp z))')) and @('p'') and @('q'') are inductive instances of @('p') and
 @('q').  Promotion produces</p>

 @({
    ( c  & p & (p'  --->  q'))
  --->
    q
 })

 <p>It is then very common to prove that @('p') implies @('p''),</p>

 <code>
 <i>(i)</i>:
 (c &amp; p) ---&gt; p'
 </code>

 <p>and then prove that @('q'') implies @('q'),</p>

 <code>
 <i>(ii)</i>:
 (c &amp; p &amp; q') ---&gt; q
 </code>

 <p>These correspond exactly to our choices <i>Subgoal (i)</i> and <i>Subgoal
 (ii)</i>.</p>

 <p>It is sometimes helpful to remember this diagram:</p>

 @({
  (c  &  (p'  --->  q')
          ^         |
          |         |
          |         v
   -->   (p   --->  q )
 })

 <p>When you understand why <i>Subgoals (i)</i> and <i>(ii)</i> are sufficient,
 use your browser's <b>Back Button</b> to return to @(see
 logic-knowledge-taken-for-granted) and go to question Q3.</p>")

(defxdoc logic-knowledge-taken-for-granted-q3-answer
  :parents (introduction-to-the-theorem-prover)
  :short "The inductive step of the @('rev-rev') proof — Answer to Question 2"
  :long "<p>The correct answer to Question 3 in @(see
 logic-knowledge-taken-for-granted) is that you need to prove</p>

 <code>
 <i>Subgoal to Relieve Hyp 1</i>:
 (implies (and (q (f a))
               (r a))
          (p (f a)))
 </code>

 <p>in order to use</p>

 <code>
 <i>Theorem</i>:
 (implies (p (f x))
          (equal (g (h x))
                 x))
 </code>

 <p>to rewrite the target @('(g (h a))') to @('a') in</p>

 <code>
 <i>Goal Conjecture</i>:
 (implies (and (q (f a))
               (r a))
          (s (g (h a))))
 </code>

 <p>If you don't see why, re-read the discussion of <see topic='@(url
 LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-REWRITING)'>rewriting</see> again.
 Forgetting about the need to relieve hypotheses is a common mistake in
 informal proofs.  ACL2 won't forget to relieve them.  But if you forget about
 the need to do it, you may be confused when ACL2 doesn't see the ``proof'' you
 see!</p>

 <p>Now use your browser's <b>Back Button</b> to return to the end of quiz in
 @(see logic-knowledge-taken-for-granted).</p>")

(defxdoc logic-knowledge-taken-for-granted-rewriting
  :parents (introduction-to-the-theorem-prover)
  :short "A brief explanation of rewriting from the logical perspective"
  :long "<p>First we give two examples of rewriting.  Then we give a rather
 detailed description.  We recommend you read the description, even if you
 understand the two examples, just so that you learn our terminology.</p>

 <p><b>Example 1</b>: Suppose your goal conjecture is:</p>

 <code>
 <i>Goal Conjecture</i>:
 (implies (and (endp z)
               (true-listp z))
          (equal (rev (rev z)) z))
 </code>

 <p>Then you can use the following theorem (actually the definitional axiom
 introduced by the @('defun') of @('endp')):</p>

 <code>
 <i>Definitional Axiom</i>: endp
 (equal (endp x)
        (not (consp x))).
 </code>

 <p>to <i>rewrite</i> the <i>Goal Conjecture</i> to</p>

 <code>
 <i>Rewritten Goal Conjecture</i>:
 (implies (and (not (consp z))
               (true-listp z))
          (equal (rev (rev z)) z))
 </code>

 <p>Note that in this example, rewriting replaced the call of @('endp') by its
 body after instantiating its body with the actuals from the call.  This is
 sometimes just called <i>expanding</i> the definition of @('endp').  (The
 notions of <i>formal</i>, <i>body</i>, <i>call</i>, and <i>actuals</i> are
 discussed in @(see programming-knowledge-taken-for-granted).)</p>

 <p>Expanding a definition is an example of <i>unconditional</i> rewriting.
 All definitions in ACL2 are just bare equalities relating a call of the
 function on its formals to its body.  Any time you use an equality theorem,
 whether a definitional equality or something more general like</p>

 @({
  (equal (append (append x y) z)
         (append x (append y z)))
 })

 <p>to replace an instance of one side by the corresponding instance of the
 other in a goal conjecture, we call that <i>unconditional</i> rewriting with
 the equality.</p>

 <p><b>Example 2</b>: Suppose your goal conjecture is:</p>

 <code>
 <i>Goal Conjecture</i>:
 (implies (and (subsetp a b)
               (true-listp b)
               (member e a))
          (&lt; (len (rm e b)) (len b))).
 </code>

 <p>This conjecture may be read ``if @('a') is a subset of the @('true-listp')
 @('b') and @('e') is a member of @('a'), then the result of removing @('e')
 from @('b') has a shorter length than @('b').''</p>

 <p>You can use the following theorem:</p>

 <code>
 <i>Theorem</i>:
 (implies (member u v)
          (equal (len (rm u v))
                 (- (len v) 1)))
 </code>

 <p>to <i>rewrite</i> the <i>Goal Conjecture</i> to</p>

 <code>
 <i>Rewritten Goal Conjecture</i>:
 (implies (and (subsetp a b)
               (true-listp b)
               (member e a))
          (&lt; (- (len b) 1) (len b))).
 </code>

 <p>To do this you must know that the following subgoal is provable:</p>

 <code>
 <i>Subgoal to Relieve Hyp 1</i>:
 (implies (and (subsetp a b)
               (true-listp b)
               (member e a))
          (member e b)).
 </code>

 <p>This is an example of <i>conditional</i> rewriting.  In order to use the
 <i>Theorem</i> we had to establish that its hypotheses are satisfied.  That is
 called <i>relieving the hypotheses</i> and was done by proving the <i>Subgoal
 to Relieve Hyp 1</i>.  Conditional rewriting is the most commonly used proof
 technique in ACL2.</p>

 <p>Unconditional rewriting is just a special case, where there are no
 hypotheses to relieve.</p>

 <p>Expanding a definition is just another special case, where there are no
 hypotheses to relieve and the pattern is easy to match because it is a call of
 a function on distinct variables.</p>

 <p>This page discusses <i>rewriting</i> from the logical perspective.  It is
 important that you are familiar with the notions of a <i>target</i> term being
 an <see topic='@(url
 LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-INSTANCE)'>instance</see> of a
 <i>pattern</i> term.  We often say the pattern <i>matches</i> the target.
 These notions involve a corresponding <i>substitution</i> of terms for
 variables.  All these notions are discussed in the link for ``<see
 topic='@(url LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-INSTANCE)'>instance</see>''
 above and we recommend you read it before continuing.  Then use your browser's
 <b>Back Button</b> to come back here.</p>

 <p>You should also be aware of the terms introduced in our discussion of <see
 topic='@(url
 LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-PROPOSITIONAL-CALCULUS)'>propositional
 calculus</see>.</p>

 <p><i>Rewriting</i> is a fundamental rule of inference in our system.  The
 rule allows you to use a theorem, i.e., an axiom, lemma, or definition, to
 replace one term by another in the goal conjecture you're trying to prove.</p>

 <p>Suppose you have a theorem that is of the form (or can be put into the
 form):</p>

 <code>
 <i>Theorem</i>:
 (implies (and <i>hyp1</i>
               ...
               <i>hypk</i>)
          (equal <i>pattern</i>
                 <i>replacement</i>))
 </code>

 <p>From the logical perspective we don't care how the theorem was actually
 written when it was proved.  It might have no hypotheses (in which case the
 <i>hypi</i> could just be @('t')), or it could have been written in a
 different but equivalent propositional style, @('(or (not') <i>hyp1</i>@(')
 ...)'), or the equality could have been written the other way around,
 @('(equal ')<i>replacement</i> <i>pattern</i>@(')').  Such syntactic details
 don't matter.  Just take a theorem and use propositional calculus to rearrange
 it equivalently into this form for the purposes of this one rewrite step.</p>

 <p>Suppose some target term, <i>target</i> that occurs in your goal conjecture
 is an instance of <i>pattern</i>.  Let the corresponding substitution be
 <i>sigma</i>.  If <i>sigma</i> does not contain a binding for every variable
 that occurs in <i>Theorem</i>, then extend <i>sigma</i> to <i>sigma'</i> by
 adding one binding for each such variable.  (This is necessary only if
 <i>pattern</i> does not contain every variable in <i>Theorem</i>.)</p>

 <p>Let <i>replacement'</i> be the result of instantiating <i>replacement</i>
 with <i>sigma'</i>.  Let <i>hypi'</i> be the result of instantiating
 <i>hypi</i> with <i>sigma'</i>.</p>

 <p>Then the <b>Rewrite Rule of Inference</b> tells us it is permitted to
 replace that occurrence of <i>target</i> in the goal by <i>replacement'</i>
 &mdash; <b>if you can prove</b> each <i>hypi'</i> in this context.  We make
 this last condition clear in a moment.</p>

 <p>The justification for this is that <i>Theorem</i> is true for all values of
 the variables.  Hence, it is true for the values specified by <i>sigma'</i>.
 If the <i>hypi'</i> are true, then the target is really equal to
 <i>replacement'</i>.  But it is always permitted to replace something by
 something it's equal to.</p>

 <p>Rewriting thus involves several steps:</p>

 <p>(1) Finding a <i>target</i> and a <i>theorem</i> to use to rewrite it to
 some more desirable <i>replacement</i>.</p>

 <p>(2) Instantiating <i>pattern</i> in the (rearranged) theorem to match
 <i>target</i>.</p>

 <p>(3) Extending <i>sigma</i> to <i>sigma'</i> to bind all the variables in
 <i>Theorem</i>.</p>

 <p>(4) Establishing that the <i>sigma'</i> instances of each of the
 <i>hypi</i> hold.  This is called <i>relieving the hypotheses</i> of the
 theorem and is discussed in greater detail below.</p>

 <p>(5) Replacing the occurrence of <i>target</i> in the goal conjecture by the
 <i>sigma'</i> instance of <i>replacement</i>, provided all the hypotheses are
 relieved.</p>

 <p>Step (4) above, <i>relieving the hypotheses</i>, requires first identifying
 the ``context'' of the target in the goal conjecture.  To do this, use
 propositional calculus to rearrange the goal conjecture so the occurrence of
 <i>target</i> is in the conclusion and let <i>context</i> be the
 hypothesis.</p>

 <code>
 <i>Rearranged Conjecture</i>:
 (implies <i>context</i>
          (... <i>target</i> ...))
 </code>

 <p>To relieve the hypotheses you must then prove each of the following
 subgoals:</p>

 <code>
 <i>Subgoal to Relieve Hyp i</i>:
 (implies <i>context</i> <i>hypi'</i>).
 </code>

 <p>It is important to note that this description of rewriting with
 <i>Theorem</i> describes the process from a strictly logical perspective.  The
 syntax of the theorem and the goal don't matter.  You're free to use
 propositional calculus to rearrange them to put them into the appropriate
 forms to fit the descriptions given.  Clearly, if you have a candidate Theorem
 in the ``wrong'' form and but it can be rearranged with propositional calculus
 into the ``right'' form, then that rearranged theorem is also a <i>Theorem</i>
 and can be used as described.  But in the actual implementation of ACL2, the
 syntactic form of a proved <i>Theorem</i> affects how it is used by rewriting.
 If a proved theorem takes the form of an implication concluding with an
 equality, ACL2 treats the left-hand side of the equality as <i>pattern</i> and
 the right-hand side as <i>replacement</i>, unless you tell it otherwise.
 We'll discuss this later.</p>

 <p>Furthermore, being from the logical perspective this discussion of
 rewriting does not address (a) how you extend <i>sigma</i> to <i>sigma'</i>
 &mdash; any extension will do provided it allows you to relieve the
 hypotheses.  The ACL2 theorem prover uses certain heuristics which we'll
 discuss later, including methods by which you can guide the system in the
 selection.</p>

 <p>Crucially, it does not discuss whether it is a <i>good idea</i> to do a
 particular rewrite!  For example, the definitional equality:</p>

 @({
  (equal (len x)
         (if (endp x)
             0
             (+ 1 (len (cdr x)))))
 })

 <p>may be used repeatedly, endlessly, to replace @('(len a)') by an ever
 growing sequence of terms:</p>

 @({
  (len a)
  =
  (if (endp a)
      0
      (+ 1 (len (cdr a))))
  =
  (if (endp a)
      0
      (+ 1 (if (endp (cdr a))
               0
               (+ 1 (len (cdr (cdr a)))))))
  = ...
 })

 <p>The ACL2 implementation of rewriting uses certain heuristics and you can
 guide the system in its choices.  We'll discuss this later.</p>

 <p>Now use your browser's <b>Back Button</b> to return to the example proof in
 @(see logic-knowledge-taken-for-granted).</p>")

(defxdoc logic-knowledge-taken-for-granted-rewriting-repeatedly
  :parents (introduction-to-the-theorem-prover)
  :short "Further information on expanding definitions via rewriting"
  :long "<p>We assume you've read about ``<see topic='@(url
 LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-INSTANCE)'>instances</see>'' and picked up
 our basic terminology including the ideas of <i>matching</i> a <i>pattern</i>
 term to a <i>target</i> term, obtaining a <i>substitution</i> and how to
 <i>instantiate</i> a term with a substitution.  We use these notions below
 without further citation.</p>

 <p>In addition, we assume you've read about ``<see topic='@(url
 LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-REWRITING)'>rewriting</see>'' where we
 introduced the idea of treating a theorem (axiom, definition, or lemma) as a
 <i>conditional rewrite</i> rule and replaced one term by an equivalent one
 provided we can <i>relieve the hypotheses</i>.</p>

 <p>Suppose you're trying to prove <i>formula1</i> and you transform it to
 <i>formula2</i> by rewriting.  What happened?</p>

 <code>
 <i>formula1</i>:
 (implies (and (not (consp z))
               (true-listp z))
          (equal (rev (rev z)) z))

 <i>formula2</i>:
 (implies (and (not (consp z))
               (equal z nil))
          (equal (rev (rev z)) z))
 </code>

 <p>Evidently we replaced @('(true-listp z)') by @('(equal z nil)').  But how
 did that happen?  What really happened was the sequential application of
 several unconditional rewrites and the use of replacement of equals by
 equals.</p>

 <p>The definition of @('true-listp') is:</p>

 @({
  (defun true-listp (x)
    (if (consp x)
        (true-listp (cdr x))
        (equal x nil))).
 })

 <p>By rewriting once with the definition of @('true-listp'), we transform
 <i>formula1</i> to:</p>

 <code>
 <i>formula1'</i>:
 (implies (and (not (consp z))
               (if (consp z)
                   (true-listp (cdr z))
                   (equal z nil)))
          (equal (rev (rev z)) z)).
 </code>

 <p>Note how the call of @('true-listp') has been replaced by the entire body
 of @('true-listp').</p>

 <p>Next, note that the first hypothesis above is that @('(consp z)') is false.
 That is, @('(not (consp z))') is the same as @('(equal (consp z) nil)').
 Thus, replacement of equals by equals means we can transform <i>formula1'</i>
 to</p>

 <code>
 <i>formula1''</i>:
 (implies (and (not (consp z))
               (if nil
                   (true-listp (cdr z))
                   (equal z nil)))
          (equal (rev (rev z)) z)).
 </code>

 <p>(We will explore replacement of equals by equals later.)</p>

 <p>Furthermore, we know the basic axiom about @('if'):</p>

 <code>
 <i>Axiom</i> if-nil:
 (if nil x y) = y.
 </code>

 <p>Rewriting with this particular axiom, using @('(if nil x y)') as the
 pattern and @('y') as the replacement, will transform <i>formula1''</i> to</p>

 <code>
 <i>formula2</i>:
 (implies (and (not (consp z))
               (equal z nil))
          (equal (rev (rev z)) z)).
 </code>

 <p>Often when we say we derived one formula from another by ``expansion'' and
 or by ``rewriting'' we take many rewrite steps, as here.  We typically use
 hypotheses of the formula without noting ``replacement of equals by equals''
 as when we replaced @('(consp z)') by @('nil'), and we typically omit to
 mention the use of basic axioms like @('if-nil') above.</p>

 <p>Now use your browser's <b>Back Button</b> to return to the example proof in
 @(see logic-knowledge-taken-for-granted).</p>")

(defxdoc logic-term-list-listp
  :parents (termp acl2-built-ins)
  :short "Recognizer for lists of lists of @(see term)s that call only
 @(':')@(tsee logic)-mode function symbols"
  :long "<p>This predicate strengthens @('(term-list-listp x wrld)'), as it
 also requires @('(logic-fns-list-listp x wrld)'), i.e., that every function
 symbol called in @('x') is in @(':')@(tsee logic) mode in the @(see world),
 @('wrld').</p>

 @(def logic-term-list-listp)")

(defxdoc logic-term-listp
  :parents (termp acl2-built-ins)
  :short "Recognizer for lists of @(see term)s that call only @(':')@(tsee
 logic)-mode function symbols"
  :long "<p>This predicate strengthens @('(term-listp x wrld)'), as it also
 requires @('(logic-fns-listp x wrld)'), i.e., that every function symbol
 called in @('x') is in @(':')@(tsee logic) mode in the @(see world),
 @('wrld').</p>

 @(def logic-term-listp)")

(defxdoc logic-termp
  :parents (termp acl2-built-ins)
  :short "Recognizer for @(see term)s that call only @(':')@(tsee logic)-mode
 function symbols"
  :long "<p>This predicate strengthens @('(termp x wrld)'), as it also requires
 @('(logic-fnsp x wrld)'), i.e., that every function symbol called in @('x') is
 in @(':')@(tsee logic) mode in the @(see world), @('wrld').</p>

 @(def logic-termp)")

(defxdoc logical-name
  :parents (events world)
  :short "A name created by a logical event"
  :long "@({
  Examples:
  assoc
  caddr
  +
  "ACL2-USER"
  :here
 })

 <p>A logical name is either a name introduced by some event, such as @(tsee
 defun), @(tsee defthm), or @(tsee defpkg), or else is the keyword @(':here'),
 which refers to the most recent such event.  See @(see events).  Every logical
 name is either a symbol or a package name (a string).  For the syntactic rules
 on names, see @(see name).  The symbols name functions, macros, constants,
 axioms, theorems, labels, and @(see theories).  The strings name packages.  We
 permit the keyword symbol @(':here') to be used as a logical name denoting the
 most recently completed event.</p>

 <p>Logical names are used primarily in the theory manipulation functions,
 e.g., @(tsee universal-theory) and @(tsee current-theory) with which you may
 obtain some standard @(see theories) as of some point in the historical past.
 The reference points are the introductions of logical names, i.e., the past is
 determined by the @(see events) it contains.  One might ask, ``Why not discuss
 the past with the much more flexible language of @(see command) descriptors?''
 (See @(see command-descriptor).)  The reason is that inside of such @(see
 events) as @(tsee encapsulate) or macro @(see command)s that expand to @(tsee
 progn)s of @(see events), @(see command) descriptors provide too coarse a
 grain.</p>

 <p>When logical names are used as referents in theory expressions used in
 @(see books), one must consider the possibility that the defining event within
 the book in question becomes redundant by the definition of the name prior to
 the assumption of the book.  See @(see redundant-events).</p>")

(defxdoc logior
  :parents (numbers acl2-built-ins)
  :short "Bitwise logical inclusive or of zero or more integers"
  :long "<p>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
 @('(the integer x)').</p>

 <p>The @(see guard) for @('binary-logior') requires its arguments to be
 integers.  @('Logior') is defined in Common Lisp.  See any Common Lisp
 documentation for more information.</p>

 @(def logior)
 @(def binary-logior)")

(defxdoc lognand
  :parents (numbers acl2-built-ins)
  :short "Bitwise logical `nand' of two integers"
  :long "<p>When integers are viewed in their two's complement representation,
 @('lognand') returns their bitwise logical `nand'.</p>

 <p>The @(see guard) for @('lognand') requires its arguments to be integers.
 @('Lognand') is defined in Common Lisp.  See any Common Lisp documentation for
 more information.</p>

 @(def lognand)")

(defxdoc lognor
  :parents (numbers acl2-built-ins)
  :short "Bitwise logical `nor' of two integers"
  :long "<p>When integers are viewed in their two's complement representation,
 @('lognor') returns the bitwise logical `nor' of the first with the
 second.</p>

 <p>The @(see guard) for @('lognor') requires its arguments to be integers.
 @('Lognor') is defined in Common Lisp.  See any Common Lisp documentation for
 more information.</p>

 @(def lognor)")

(defxdoc lognot
  :parents (numbers acl2-built-ins)
  :short "Bitwise not of a two's complement number"
  :long "<p>@('(lognot i)') is the two's complement bitwise @('`not'') of the
 integer @('i').</p>

 <p>@('Lognot') is actually defined by coercing its argument to an integer (see
 @(see ifix)), negating the result, and then subtracting @('1').</p>

 <p>The @(see guard) for @('lognot') requires its argument to be an
 integer.</p>

 <p>@('Lognot') is a Common Lisp function.  See any Common Lisp documentation
 for more information.</p>

 @(def lognot)")

(defxdoc logorc1
  :parents (numbers acl2-built-ins)
  :short "Bitwise logical inclusive or of two ints, complementing the first"
  :long "<p>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.</p>

 <p>The @(see guard) for @('logorc1') requires its arguments to be integers.
 @('Logorc1') is defined in Common Lisp.  See any Common Lisp documentation for
 more information.</p>

 @(def logorc1)")

(defxdoc logorc2
  :parents (numbers acl2-built-ins)
  :short "Bitwise logical inclusive or of two ints, complementing the second"
  :long "<p>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.</p>

 <p>The @(see guard) for @('logorc2') requires its arguments to be integers.
 @('Logorc2') is defined in Common Lisp.  See any Common Lisp documentation for
 more information.</p>

 @(def logorc2)")

(defxdoc logtest
  :parents (numbers acl2-built-ins)
  :short "Test if two integers share a `1' bit"
  :long "<p>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.</p>

 <p>The @(see guard) for @('logtest') requires its arguments to be integers.
 @('Logtest') is defined in Common Lisp.  See any Common Lisp documentation for
 more information.</p>

 @(def logtest)")

(defxdoc logxor
  :parents (numbers acl2-built-ins)
  :short "Bitwise logical exclusive or of zero or more integers"
  :long "<p>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
 @('(the integer x)').</p>

 <p>The @(see guard) for @('binary-logxor') requires its arguments to be
 integers.  @('Logxor') is defined in Common Lisp.  See any Common Lisp
 documentation for more information.</p>

 @(def logxor)
 @(def binary-logxor)")

(defxdoc loop$
  :parents (acl2-built-ins programming)
  :short "Iteration with an analogue of the Common Lisp @('loop') macro"
  :long "<p>@('Loop$') is the ACL2 analogue of the Common Lisp's iteration
 primitive, @('loop').  This topic introduces the two classes of ACL2
 @('loop$') expressions, @('FOR') @('loop$')s and @('DO') @('loop$')s; see
 @(see for-loop$) and @(see do-loop$) (respectively) for their full
 documentation.</p>

 <p>@('Loop$') was introduced into ACL2 in Version 8.2 (May, 2019), over 20
 years after ACL2 was first released.  So there are many experienced ACL2 users
 who have never used @('loop$').  The @('Loop$') Primer, see @(see
 loop$-primer), is textbook-style introduction, meant to be read linearly and
 may be a good starting place for you.  The primer follows a &ldquo;monkey-see
 monkey-do&rdquo; approach, showing lots of examples.  Sample proofs are worked
 out in detail and then the reader is challenged to apply those lessons to
 exercises.  Solutions to the exercises are provided in books among the
 Community Books.  Depending on your preferred learning style and familiarity
 with @('loop$') and ACL2 in general, you might want to work your way through
 the primer (see @(see loop$-primer)) instead of bouncing around the hypertext
 user's manual.</p>

 <p>The Introduction below is followed by a discussion of types and guards.
 For a discussion of how to state effective lemmas about @('loop$')s and how to
 prove inductive theorems about @('loop$')s see @(see
 stating-and-proving-lemmas-about-loop$s).  Also, for a summary of how the
 rewriter handles @('apply$'), @('ev$'), and @('loop$') @(see scion)s, see
 @(see rewriting-calls-of-apply$-ev$-and-loop$-scions).</p>

 <p>But before we get started we emphasize a few key points.</p>

 <ul>

 <li>As noted, The Loop$ Primer (see @(see loop$-primer)) may be a good place
 to start if you're using ACL2 @('loop$')s for the first time.</li>

 <li>The Table of Contents of the Loop$ Primer (see @(see lp-section-0)) lists
 some sensible entry points to the primer.  You'll see sections devoted to
 examples, sample proofs, exercises, etc.  Keep the primer in mind as an
 additional resource.  For example, you might visit @('Loop$') Primer Section
 6 (@(see lp-section-6)) for some exercises on writing @('loop$')s and, when
 you get to the end, ignore the &ldquo;Now go to @(see lp-section-7),&rdquo;
 and use your browser's Back key to return to the general hypertext user's
 manual.</li>

 <li><b>Many examples</b> of @(tsee loop$) expressions may be found in @(see
 community-book) @('projects/apply/loop-tests.lisp').</li>

 <li>The semantics of @('loop$') involve @('apply$').  Therefore, before using
 @('loop$'), it is <b>strongly recommended</b> that you include the same book
 as is typically included when using @(tsee apply$), as follows.

 @({
 (include-book "projects/apply/top" :dir :system)
 })</li>

 <li>ACL2 @('loop$') statements are executed as Common Lisp @('loop')
 statements after the relevant @(see guard) conjectures are proved.  Common
 Lisp @('loop') statements generally execute much faster than
 equivalent (tail-recursive) functions.</li>

 <li><b>Warning:</b> @('Loop$') implements only a modest part of the
 functionality of Common Lisp's @('loop').  Aside from the simple fact that
 @('loop$') allows only a limited subset of the syntax of @('loop'), the main
 restriction is that the subexpressions of the @('loop$') expression that are
 evaluated repeatedly must be @(see tame)!  These expressions include not only
 the loop body but, if present, the @('UNTIL') test, the @('WHEN') test, and
 the @('FINALLY') clause (all discussed below).  Thus, all the function
 symbols used in these expressions must be @(see badge)d (see @(tsee defbadge)
 and @(tsee defwarrant)).  Further restrictions are enforced for @(tsee
 defun)'d functions in which recursive calls appear in @('loop$') bodies, but
 we say little about that in this documentation topic; see @(see
 loop$-recursion).  We recommend that users unfamiliar with @('loop$')
 acquaint themselves with the material below and in @(see for-loop$) before
 wading into @('loop$-recursion')!</li>

 </ul>

 <h3>Introduction to @('loop$')</h3>

 <p>As noted above, there are two classes of @('loop$') expressions.  These are
 identified as follows.</p>

 <ul>

 <li>@('FOR') loop$ expressions:

 @({
 (loop$ FOR ...)
 })

 </li>

 <li>@('DO') loop$ expressions:

 @({
 (loop$ WITH ... DO ...)
 })

 </li>

 </ul>

 <p>Below we introduce these two classes of @('loop$') expressions.  For full
 documentation see the topic for each class: see @(see for-loop$) for @('FOR')
 @('loop$')s and @(see do-loop$) for @('DO') @('loop$')s.  In particular
 various restrictions are discussed in those topics, but for now we mention
 just the following.  While @('FOR') @('loop$') expressions are often more
 convenient to use than @('DO') @('loop$') expressions, their @('UNTIL'),
 @('WHEN'), and body expressions are not permitted to reference @(tsee state)
 or @(see stobj)s, and they always return a single value.  @('DO') @('loop$')
 expressions do not have these restrictions, but they may not use the idioms of
 @('FOR') @('loop$')s, like ``@('FOR x IN ...')'' or ``@('UNTIL p')''.</p>

 <p>ACL2's @('loop$') is considerably more restrictive than Common Lisp's
 @('loop'), but when an ACL2 @('loop$') expression is translated without error
 it has the same meaning as the corresponding Common Lisp @('loop').
 @('Loop$') supports @(':')@(tsee GUARD) expressions (discussed below) in
 certain places and these are ignored by Common Lisp.</p>

 <p>Next we present some @('FOR') @('loop$') examples.  They illustrate the
 three supported forms of @('FOR') @('loop$') iteration: the use of @('IN'), to
 iterate over elements of a list; the use of @('ON'), to iterate over the
 non-empty tails of a list; and the use of @('FROM .. TO'), to iterate over a
 range of integers (optionally with @('BY') to specify the increment at each
 step).  These examples also illustrate the use of @('WHEN') to restrict which
 iterations are considered and the use of @('UNTIL') to terminate early.
 Additional keywords illustrated are @('OF-TYPE') to specify types and @('AS')
 to specify additional iteration variables.  They also illustrate some of the
 operations permitted at each iteration, such as @('SUM') and @('COLLECT').</p>

 @({
 ACL2 !>(loop$ for x in '(1 2 3) sum (* x x))
 14
 ACL2 !>(loop$ for x in '(1 2 3) collect (* x x))
 (1 4 9)
 ACL2 !>(loop$ for x on '(1 2 3) collect x)
 ((1 2 3) (2 3) (3))
 ACL2 !>(loop$ for x of-type integer from -10 to 10 by 2 collect x)
 (-10 -8 -6 -4 -2 0 2 4 6 8 10)
 ACL2 !>(loop$ for i from 1 to 10
               as  x in '(a b c d e f g)
               collect (cons i x))
 ((1 . A)
  (2 . B)
  (3 . C)
  (4 . D)
  (5 . E)
  (6 . F)
  (7 . G))
 ACL2 !>(loop$ for i from 1 to 10
               as  x in '(a b c d e f g)
               until (> i 6)
               collect (cons i x))
 ((1 . A)
  (2 . B)
  (3 . C)
  (4 . D)
  (5 . E)
  (6 . F))
 ACL2 !>(loop$ for i from 1 to 10
               as  x in '(a b c d e f g)
               until (> i 6)
               when (evenp i)
               collect (cons i x))
 ((2 . B) (4 . D) (6 . F))
 })

 <p>Finally we present two @('DO') @('loop$') examples.  We explore them
 further in the documentation specific to @('DO') @('loop$') expressions; see
 @(see do-loop$).</p>

 <p>Our first @('DO') @('loop$') example shows iteration with the indicated
 initial values for local variables @('x') and @('y').  They are modified at
 each iteration through the loop until @('x') is empty, at which point the
 value of @('y') is returned.  (See @(see do-loop$) for more thorough
 explanations.)</p>

 @({
 ACL2 !>(loop$ with x = '(a b c)
               with y = nil
               do (cond ((consp x)
                         (progn (setq y (cons (car x) y))
                                (setq x (cdr x))))
                        (t (return y))))
 (C B A)
 ACL2 !>
 })

 <p>Our second example of a @('DO') @('loop$') expression illustrates more
 features than the first.  Also, it illustrates the use of a @('loop$')
 expression inside a definition, which is allowed for both @('FOR') @('loop$')s
 and @('DO') @('loop$')s.  We see here that @(see stobj)s and @(see
 multiple-value) returns are allowed for @('DO') @('loop$')s, where the
 @(':VALUES') keyword specifies the shape of the return.  We also see here the
 use of the optional @(':GUARD') keyword of a @('loop$') expression (legal for
 both classes of @('loop$')s, as discussed further below) and the optional
 @(':MEASURE') keyword of a @('DO') @('loop$') expression.</p>

 <p>But notice the @(tsee defwarrant) events below!  They are required because
 the functions @('fld') and @('update-fld') are not system primitives.  They
 are introduced by the user's @(tsee defstobj) event below.  This is in
 contrast to the @('DO') @('loop$') in our first example above where no
 warrants are required because all the functions in that example are
 primitive.</p>

 <p>The semantics of @('loop$') involve @('apply$') and thus @('loop$')s
 inherit the restrictions imposed on @('apply$') and its @(see scion)s.  Among
 those restrictions are that (a) unwarranted @(':logic') mode functions cannot
 be @('apply$')'d in the top-level read-eval-print loop and (b) proofs about
 the applications of unwarranted functions are impossible.  Restriction (a)
 means you cannot even execute a @(':logic') mode @('loop$') containing
 unwarranted functions.  Restriction (b) means you can't verify the @(see
 guard)s of such @('loop$').  This last point obviates the main reason for
 using @('loop$'): its fast execution as a Common Lisp loop once guards are
 verified.</p>

 <p>Now here is our second example.</p>

 @({

 (defstobj st fld)
 (include-book "projects/apply/top" :dir :system) ; needed for defwarrant
 (defwarrant fld)
 (defwarrant update-fld)

 (defun test-loop$ (i0 max st)
   (declare (xargs :guard (and (natp i0) (natp max))
                   :stobjs st))
   (loop$ with i of-type (satisfies natp) = i0
          with cnt of-type integer = 0
          do
          :measure (nfix (- max i))
          :guard (and (natp max)
                      (natp cnt)
                      (stp st))
          :values (nil st) ; shape of return; can be omitted when it's (nil)
          (if (>= i max)
              (loop-finish)
            (progn (setq st (update-fld i st))
                   (mv-setq (cnt i)
                            (mv (+ 1 cnt) (+ 1 i)))))
          finally
          :guard (stp st)
          (return
           (mv (list 'from i0 'to max 'is cnt 'steps 'and 'fld '= (fld st))
               st))))

 ACL2 !>(test-loop$ 3 8 st)
 ((FROM 3 TO 8 IS 5 STEPS AND FLD = 7)
  <st>)
 ACL2 !>
 })

 <p>Both classes of @('loop$') expressions (@('FOR') and @('DO') @('loop$')s)
 rely heavily on the ACL2 built-in function, @(tsee apply$): in each iteration
 through the loop, a @(see lambda) object based on the body of the @('loop$')
 is given as the function argument of @('apply$').  Similarly, the @('UNTIL')
 and @('WHEN') clauses of @('FOR') @('loop$')s and the @(':measure') and
 @('FINALLY') clauses of @('DO') @('loop$')s are translated into @('lambda')
 objects.  The functions in all those @('lambda') objects must be warranted to
 evaluate the @('loop$') and/or prove its properties (including its guards)
 because logically the application of an unwarranted function is
 undefined.  (However, recall from @(see guarantees-of-the-top-level-loop) that
 @(':program') mode functions do not need warrants, just badges, for execution
 in the evaluation theory.)</p>

 <p>The documentation for @(tsee apply$) illustrates a simple @('defun') that
 is inadmissible because the measure theorem cannot be proved without a warrant
 and warrants cannot be assumed during the proofs of the measure conjectures.
 The same issue arises when one of the functions critically involved in a
 measure conjecture is defined using a @('loop$') whose body involves a
 user-defined function.  For a simple example of this issue and how to work
 around it, see @(see community-book)
 @('books/demos/measure-and-warrant.lisp').</p>

 <h3>Types and guards in @('loop$') expressions</h3>

 <p>In this section we document basic aspects of the @('OF-TYPE') and
 @(':GUARD') keywords in @(tsee loop$) expressions.  See @(see for-loop$) and
 @(see do-loop$) for detailed documentation on guards for @('FOR') and @('DO')
 @('loop$') expressions, respectively.</p>

 <p>@('Loop$') expressions execute fastest when they are @(see guard)
 verified.  But the @('loop$') body raises interesting guard verification
 problems, as do the @('UNTIL') and @('WHEN') tests of a @('FOR') @('loop$'),
 because they are executed for many different values of the iteration
 variables.  The @('FINALLY') clause of a @('DO') @('loop$') raises a similar
 concern, since the values of its variables may be modified repeatedly by
 execution of the @('loop$') body.  It may be necessary to provide type
 information or even stronger invariants to verify guards for @('loop$')s.  We
 now provide a few examples illustrating the handling of guards in
 @('loop$').</p>

 <p>The first example below is an acceptable @('loop$') expression but cannot
 be guard verified, as would be necessary if it appeared in a @(tsee defun)
 that was to be guard verified.  The problem is that @('(+ 1 x)') requires
 @('x') to be numeric and, in general, we don't know anything about the value
 of @('x') here.  (Actually, because the target range is just a constant below,
 ACL2 could deduce information about each value @('x') takes on, but it
 doesn't.)  The second example can be guard verified and has the advantage of
 being standard Common Lisp, so compilers might optimize the handing of @('(+ 1
 x)').  The third example can also be guard verified but since the @(':GUARD')
 directive used here is ignored by Common Lisp it does not inform the compiler,
 so this example might execute more slowly than the previous one.  The last
 example shows the syntax and use of the ACL2-specific addition to @('loop$'):
 the @(':GUARD') directive protecting, in this case, the @('loop$') body.
 @(':GUARD') is useful when you wish to add more guard information than can be
 expressed with the Common Lisp @('OF-TYPE') directive.  The @('OF-TYPE') and
 @(':GUARD') directives are conjoined to form the actual guard protecting the
 @('loop$') body.</p>

 @({
 ACL2 !>(loop$ for x in '(1 2 3) collect (+ 1 x))
 (2 3 4)
 ACL2 !>(loop$ for x of-type integer in '(1 2 3) collect (+ 1 x))
 (2 3 4)
 ACL2 !>(loop$ for x in '(1 2 3) collect :guard (integerp x) (+ 1 x))
 (2 3 4)
 ACL2 !>(let ((max 10))
         (loop$ for x of-type integer in '(1 2 3)
                collect
                :guard (and (integerp max) (< x max))
                (- max x)))
 (9 8 7)
 })

 <p>The guard on the @('(- max x)') above is @('(and (integerp x) (integerp
 max) (< x max))') and the compiler is informed that @('x') is an integer by
 the @('OF-TYPE').</p>

 <p>The examples just above are of @('FOR') @('loop$')s.  Here is a @('DO')
 @('loop$') example that illustrates types and guards.</p>

 @({
 ACL2 !>(loop$ with i of-type integer = 7
               with ans = nil
               do
               :guard (true-listp ans)
               (progn (setq ans (cons i ans))
                      (setq i (- i 2))
                      (if (< i 0) (loop-finish) t))
               finally
               :guard (true-listp ans)
               (return (reverse ans)))
 (7 5 3 1)
 ACL2 !>
 })

 <p>Neither @(':GUARD') is necessary in order for this execution to complete.
 However, if this @('loop$') is put into a definition &mdash; @('(defun foo ()
 (loop$ ...))') &mdash; then both @(':GUARD') expressions are necessary in
 order for the definition to be @(see guard)-verified.</p>

 <p>As suggested above, when a @('loop$') expression occurs in the body of a
 @(see guard)-verified function, it will be executed as a Common Lisp
 @('loop') expression, which can be much more efficient than executing without
 such guard verification.  This efficiency can also be gained in top-level
 @('loop$') expressions if the @(see tau-system) completes (silently) the
 necessary guard verification.  See @(see print-cl-cache).</p>")

(defxdoc loop$-primer
  :parents (loop$ documentation programming)
  :short "Primer for using @(tsee loop$)"
  :long "<h1>The Loop$ Primer</h1>

  <h3>Preface</h3>

  <p>This primer was created at the request of and with the support of
  Warren Hunt.  It was originally conceived as a standalone document,
  but it has been integrated into the ACL2 documentation to increase
  its utility.</p>

  <p>The ACL2 @(tsee loop$) feature is an iteration primitive modeled on a
  small subset of the Common Lisp @('loop') facility.  This documentation is
  an elementary introduction to @('loop$') for use in both programming and proofs.  We
  assume the reader is already an experienced ACL2 user who is just new to
  @('loop$').</p>

  <p>@('Loop$') exploits ACL2's &ldquo;higher order&rdquo; capability using @(tsee
  apply$).  Logically, @('loop$') expressions are translated into calls of
  @(see scion)s or &ldquo;mapping functions&rdquo; that map one or more @(tsee
  lambda) objects over ranges.  When @('loop$') expressions are typed into the
  ACL2 top-level loop these formal semantics are executed, which can be
  inefficient.  When @('loop$') expressions are in @(see guard) verified (see @(tsee
  verify-guards)) functions they are compiled into Common Lisp @('loop')
  expressions and are executed very efficiently.</p>

  <p>Two issues complicate the situation.  First, Common Lisp's @('loop')
  facility is extraordinarily complex, requiring a full chapter of the reference
  manual to explain.  See <a
  href='http://www.lispworks.com/documentation/HyperSpec/Body/m_loop.htm#loop'>loop</a>
  in the Common Lisp HyperSpec or Chapter 26 (pages 709-747) of Guy Steele's
  monumental <b>Common Lisp The Language, Second Edition</b>.  Second, ACL2's
  logic is first-order, not higher-order, and so the @('apply$')-based
  semantics imposes restrictions that new users of ACL2 may find hard to deal
  with.</p>

  <p>This primer focuses on how to write @('loop$') expressions and how to prove things
  about them.  We start by asking you some questions that test your basic
  knowledge of ACL2, so that you can decide whether this primer is right for
  you.  Then we discuss the so-called &ldquo;@('FOR')&rdquo; @('loop$') and
  later move on to the &ldquo;@('DO')&rdquo; @('loop$').  We follow the
  &ldquo;monkey see, monkey do&rdquo; teaching style.  We informally and
  incompletely sketch the syntax and semantics, but we provide lots of examples
  and we offer many challenge problems for you to solve.  Answers are also
  provided.</p>

  <p>There are two glaring omissions in this primer: @(see guard) verification and the
  use of @(see stobj)s in @('DO') @('loop$').</p>

  <p>While guard verification is crucial to the efficient execution of
  @('loop$')s by Common Lisp, we omitted much discussion of it because guard
  obligations are generated automatically and are generally just
  &ldquo;ordinary&rdquo; conjectures that we assume the experienced user can
  figure out how to prove.  The newcomer to @('loop$') may wonder &ldquo;why am
  I having to prove this?&rdquo; but the answer is always the same: &ldquo;the
  Common Lisp compiler requires this in order for @('loop$') to behave like
  @('loop').&rdquo;  Often the &ldquo;fix&rdquo; to a @('loop$') guard
  verification problem is to add a @(':guard') to the @('loop$') body,
  remembering that it is translated into a @('lambda') object that must be
  guard verified in isolation since it might be passed around and applied in
  many contexts.  We include the syntax for @('loop$') guards.</p>

  <p>We omitted much discussion of stobjs &mdash; which are allowed in @('DO')
  @('loop$')s but not in other kinds of @('loop$')s &mdash; because they raise
  the same problems in @('DO') @('loop$')s as they do in &ldquo;ordinary&rdquo;
  uses: syntactic single-threadedness into, through, and out of expressions.
  We assume the experienced user knows how to deal with these issues.</p>

  <p>There is a strong emphasis in this primer on problems for you to work on.
  The best way to learn how to do something is to practice doing it!</p>

  <p>The primer is divided into subjects listed in the Table of Contents which
  is at the link @(see lp-section-0).  We recommend you read these sections in
  the order shown.  Each section ends with a pointer to the next section but
  also includes a link to the Table of Contents.</p>

  <p>Now go to @(see lp-section-1).  The Table of Contents is at @(see
  lp-section-0).</p>")

(order-subtopics loop$-primer
  (lp-section-0 lp-section-1
    lp-section-2
    lp-section-3
    lp-section-4
    lp-section-5
    lp-section-6
    lp-section-7
    lp-section-8
    lp-section-9
    lp-section-10
    lp-section-11
    lp-section-12
    lp-section-13
    lp-section-14
    lp-section-15
    lp-section-16
    lp-section-17
    lp-section-18))

(defxdoc lp-section-0
  :parents (loop$-primer)
  :short "Loop$ Primer Table of Contents)"
  :long "<h3>The Loop$ Primer Table of Contents</h3>

  <ul>
  <li>@(see loop$-primer):&nbsp;&nbsp; Preface<br/></li>
  <li>lp-section-0:&nbsp;&nbsp; Table of Contents<br/></li>
  <li>@(see lp-section-1):&nbsp;&nbsp; Background Reviews<br/></li>
  <li>@(see lp-section-2):&nbsp;&nbsp; @('Loop') in Common Lisp and @('loop$') in ACL2<br/></li>
  <li>@(see lp-section-3):&nbsp;&nbsp; Examples of @('FOR') @('Loop$')s<br/></li>
  <li>@(see lp-section-4):&nbsp;&nbsp; Syntax of @('FOR') @('Loop$')s<br/></li>
  <li>@(see lp-section-5):&nbsp;&nbsp; Informal Semantics of @('FOR') @('Loop$')s<br/></li>
  <li>@(see lp-section-6):&nbsp;&nbsp; Challenge Problems about @('FOR') @('Loop$')s<br/></li>
  <li>@(see lp-section-7):&nbsp;&nbsp; Using @('Loop$')s and Guards in @('Defun')s<br/></li>
  <li>@(see lp-section-8):&nbsp;&nbsp; Challenge Problems about @('FOR') @('Loop$') in @('Defun')s<br/></li>
  <li>@(see lp-section-9):&nbsp;&nbsp; Semantics of @('FOR') @('Loop$')s<br/></li>
  <li>@(see lp-section-10): The Evaluation of the Formal Semantics of a Fancy @('Loop$')<br/></li>
  <li>@(see lp-section-11): Proving Theorems about @('FOR') @('Loop$')s<br/></li>
  <li>@(see lp-section-12): Challenge Proof Problems about @('FOR') @('Loop$')s<br/></li>
  <li>@(see lp-section-13): Examples of @('DO') @('Loop$')s<br/></li>
  <li>@(see lp-section-14): Challenge Problems about @('DO') @('Loop$')s<br/></li>
  <li>@(see lp-section-15): Informal Syntax and Semantics of @('DO') @('Loop$')s<br/></li>
  <li>@(see lp-section-16): Proving Theorems about @('DO') @('Loop$')s<br/></li>
  <li>@(see lp-section-17): Challenge Proof Problems for @('DO') @('Loop$')s<br/></li>
  <li>@(see lp-section-18): Conclusion<br/></li>
  <li>lp-section-0:&nbsp;&nbsp; Table of Contents<br/></li>
  </ul>
  ")

(defxdoc lp-section-1
  :parents (loop$-primer)
  :short "Background Reviews"
  :long "<h3>LP1: Background Reviews</h3>

  <p>We assume you're familiar with elementary Common Lisp and ACL2.  The
  questions and answers in @(see lp-background-review-1) offer a
  quick review.  Come back here when you're comfortable with such
  questions.</p>

  <p>@('Loop$') makes extensive use of ACL2's limited second order
  functionality.  The questions and answers in @(tsee
  lp-background-review-2) offer a quick review of the main features
  and limitations of @('apply$') and the related concepts.  We assume you're
  comfortable with these features too.</p>

  <p>Now go to @(see lp-section-2) (or return to the <see topic='@(url
  lp-section-0)'> Table of Contents</see>).</p>")

(defxdoc lp-section-2
  :parents (loop$-primer)
  :short "@('Loop') in Common Lisp and @('loop$') in ACL2"
  :long "<h3>LP2: @('Loop') in Common Lisp and @('loop$') in ACL2</h3>

  <p>The @('loop') macro of Common Lisp was inspired by the &ldquo;iterative
  statements&rdquo; in Warren Teitelman's CLISP package of Interlisp (1974).  But
  programming languages have had iterative statements since early in the
  development of compilers.  The first release of a FORTRAN compiler (1957)
  supported what is probably the most well-known iterative construct, the &ldquo;DO
  loop.&rdquo;  But CLISP added many additional features including simultaneous
  looping over multiple ranges, structured ways to filter the elements,
  structured exit control mechanisms, and multiple ways to accumulate the
  results.  Common Lisp supports these and many other features.</p>

  <p>ACL2's @('loop$') facility supports a tiny subset of Common Lisp's
  @('loop') statements.  It is hard to overstate how small the ACL2 subset is!
  For example, to manage iteration over a range of numbers, ACL2 provides
  @('FROM'), @('TO'), and @('BY'), but Common Lisp additionally provides
  @('DOWNFROM'),@('UPFROM'),@('DOWNTO'),@('UPTO'),@('BELOW'),and @('ABOVE').
  For value accumulation, ACL2 supports @('SUM'), @('COLLECT'), @('APPEND'),
  @('ALWAYS'), and @('THEREIS'), while Common Lisp also supports @('NCONC'),
  @('COUNT'), @('MAXIMIZE'), and @('MINIMIZE').  Even within its restricted
  subset, ACL2 syntax is less flexible regarding the order of the various
  &ldquo;clauses&rdquo; and the presence of, say, multiple accumulators.  The list of
  differences could go on and on because the Common Lisp facility is so
  elaborate.</p>

  <p>While many more Common Lisp @('loop') features could be supported in ACL2,
  we believe it is best to test and refine the techniques reasoning about
  @('loop$') before elaborating it further.</p>

  <p>Now go to @(see lp-section-3) (or return to the <see topic='@(url lp-section-0)'>
  Table of Contents</see>).</p>")

(defxdoc lp-section-3
  :parents (loop$-primer)
  :short "Examples of @('FOR') @('Loop$')s"
  :long "<h3>LP3: Examples of @('FOR') @('Loop$')s</h3>

  <p>Below is the complete log of an ACL2 session demonstrating the behavior of
  @('FOR') @('loop$')s.  ACL2 also supports @('DO') @('loop$')s but they are
  not illustrated here.  Note that to use @('loop$') one should always work in
  a session in which the book shown below is included.  The examples below do
  not illustrate guards, the use of user defined functions in @('loop$')
  expressions, or proofs about @('loop$')s.</p>

  <p>We'll describe the syntax and semantics of @('loop$') in the next two
  sections. But we expect you can intuit the syntax and semantics of @('loop$')
  statements from these examples alone.  Please try!</p>

  @({
  ACL2 !>(include-book "projects/apply/top" :dir :system)

  Summary
  Form:  ( INCLUDE-BOOK "projects/apply/top" ...)
  Rules: NIL
  Time:  1.00 seconds (prove: 0.00, print: 0.00, other: 1.00)
   "/Users/demo/books/projects/apply/top.lisp"

  ACL2 !>(loop$ for x in '(a b c)
                collect (cons 'hi x))
  ((HI . A) (HI . B) (HI . C))

  ACL2 !>(loop$ for x in '(a b c)
                when (not (eq x 'b))
                collect (cons 'hi x))
  ((HI . A) (HI . C))

  ACL2 !>(loop$ for x in '(a b c d e f g)
                until (eq x 'd)
                collect x)
  (A B C)

  ACL2 !>(loop$ for x on '(a b c)
                collect x)
  ((A B C) (B C) (C))

  ACL2 !>(loop$ for x on '(a b c)
                collect (cons (car x) (len x)))
  ((A . 3) (B . 2) (C . 1))

  ACL2 !>(loop$ for i from 1 to 10 sum i)
  55

  ACL2 !>(loop$ for i from 1 to 12 by 3
                collect (* i i))
  (1 16 49 100)

  ACL2 !>(loop$ for x in '((a b c) (d e f) (g h i))
                collect (cons 'hi x))
  ((HI A B C) (HI D E F) (HI G H I))

  ACL2 !>(loop$ for x in '((a b c) (d e f) (g h i))
                append (cons 'hi x))
  (HI A B C HI D E F HI G H I)

  ACL2 !>(loop$ for x in '(2 4 6)
                always (evenp x))
  T

  ACL2 !>(loop$ for x in '(2 4 5 6)
                always (evenp x))
  NIL

  ACL2 !>(loop$ for x in '(2 4 5 6)
                thereis (if (evenp x) nil x))
  5

  ACL2 !>(let ((greeting 'hi))
           (loop$ for x in '(a b c)
                  collect (cons greeting x)))
  ((HI . A) (HI . B) (HI . C))

  ACL2 !>(loop$ for x in '(a b c)
                as  y in '(65 66 67 68)
                collect (cons x y))
  ((A . 65) (B . 66) (C . 67))

  ACL2 !>(loop$ for x in '(a b c d)
                as  y in '(65 66 67)
                collect (cons x y))
  ((A . 65) (B . 66) (C . 67))

  ACL2 !>(loop$ for x in '((1 2 3) (4 5 6) (7 8 9))
                collect
                (loop$ for i in x collect (* i i)))
  ((1 4 9) (16 25 36) (49 64 81))
  })

  <p>Now go to @(see lp-section-4) (or return to the <see topic='@(url
  lp-section-0)'>Table of Contents</see>).</p>")

(defxdoc lp-section-4
  :parents (loop$-primer)
  :short "Syntax of @('FOR') @('Loop$')s"
  :long "<h3>LP4: Syntax of @('FOR') @('Loop$')s</h3>

  <p>To describe the syntax of @('FOR') @('loop$')s we first describe the most
  elaborate @('FOR') @('loop$').  Then we note which elements can be omitted.
  The most elaborate @('FOR') @('loop$') is of the form</p>

  <p>&nbsp; &nbsp; &nbsp; &nbsp; @('(LOOP$ FOR ')<i>v1</i>@(' OF-TYPE ')<i>spec1
  target1</i><br/> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
  &nbsp; &nbsp; &nbsp; &nbsp; @('AS ') &nbsp; <i>v2</i>@(' OF-TYPE ')<i>spec2
  target2</i><br/> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
  &nbsp; &nbsp; &nbsp; &nbsp; ...<br/> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
  &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; @('AS ') &nbsp; <i>vn</i>@('
  OF-TYPE ')<i>specn targetn</i><br/> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
  &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; @('UNTIL :GUARD ')<i>guard1
  until-expr</i><br/> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
  &nbsp; &nbsp; &nbsp; &nbsp; @('WHEN ') &nbsp; @(':GUARD ')<i>guard2
  when-expr</i><br/> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
  &nbsp; &nbsp; &nbsp; <i>op</i>@(' :GUARD ')<i>guard3
  body-expr</i>@(')')<br/></p>

  <p>where</p>

  <ul>

  <li>each <i>vi</i> &nbsp; is a legal variable symbol, they are all distinct,
  and are collectively called the <i>iteration variables</i>,</li>

  <li>each <i>speci</i> &nbsp; is a @(tsee type-spec) for the corresponding
  variable <i>vi</i>,</li>

  <li>each <i>targeti</i> is of one of the forms below and specifies the range
  of values to be taken by the corresponding variable <i>vi</i>.  Abstractly
  you may think of the &ldquo;range&rdquo; here simply as a list of the values as
  described below, where <i>list-expr</i> is a term (which is expected to
  evaluate to a true list), <i>lo-expr</i> and <i>hi-expr</i> are terms (which
  are expected to evaluate to integers), and <i>step-expr</i> is a term (which
  is expected to evaluate to a positive integer).  In the examples given below,
  let @('rv') be the list reverse function, so @('(rv '(a b c))') is @('(C B A)').

  <ul>

  <li>@('IN') <i>list-expr</i> &mdash; range is the value of <i>list-expr</i>.
  For example, the range of &ldquo;@('IN') @('(rv '(a b c))')&rdquo; is @('(C B
  A)').</li>

  <li>@('ON') <i>list-expr</i> &mdash; range is the list of successive
  non-@('nil') tails of the value of <i>list-expr</i>.  For example, the range
  of &ldquo;@('ON') @('(rv '(a b c))')&rdquo; is @('((C B A) (B A) (A))').  The range
  value is produced by @('(TAILS ')<i>list-expr</i>@(')').</li>

  <li>@('FROM') <i>lo-expr</i> @('TO') <i>hi-expr</i> @('BY') <i>step-expr</i>
  &mdash; If &ldquo;@('BY') <i>step-expr</i>&rdquo; is omitted, &ldquo;@('BY 1')&rdquo; is used.
  The range contains all the integers from the value of <i>lo-expr</i> to the
  greatest integer less than or equal to the value of <i>hi-expr</i> such that
  each is separated from its higher neighbor by the value of <i>step-expr</i>.
  For example, the range of &ldquo;@('FROM') 1 @('TO') 10 @('BY') 2&rdquo; is @('(1 3 5 7
  9)').  The range value is produced by @('(FROM-TO-BY ')<i>lo-expr</i>
  <i>hi-expr</i> <i>step-expr</i>@(')').</li>

  </ul>
  </li>

  <li>each <i>guardi</i> is a term,</li>

  <li>each <i>until-expr</i>, <i>when-expr</i>, and <i>body-expr</i>
  &nbsp; is a @(tsee tame) term, and</li>

  <li><i>op</i> &nbsp; is one of the <i>operators</i> &nbsp;
  @('SUM'), @('COLLECT'), @('APPEND'), @('ALWAYS'), or @('THEREIS').</li>

  </ul>

  <p>The symbols @('FOR'), @('IN'), @('ON'), @('FROM'), @('TO'), @('BY'),
  @('OF-TYPE'), @('WHEN'), @('UNTIL'), @('SUM'), @('COLLECT'), @('APPEND'),
  @('ALWAYS'), and @('THEREIS') when used in @('loop$') statements may be in
  any package.</p>

  <p>Common Lisp prohibits loops with both a @('WHEN') clause and either an
  @('ALWAYS') or a @('THEREIS') operator.  For example, if you are tempted to
  write &ldquo;@('WHEN') <i>p</i> @('ALWAYS') <i>q</i>&rdquo; you can instead write
  &ldquo;@('ALWAYS') @('(if ')<i>p q</i> @('t)').&rdquo;</p>

  <p>The following elements may be omitted from the most elaborate form and
  still produce legal @('loop$') statements:</p>

  <ul>
  <li>any line beginning with @('AS'), @('UNTIL') or @('WHEN'),</li>

  <li>any @('OF-TYPE') <i>speci</i>, and</li>

  <li>any @(':GUARD') <i>guardi</i>.</li>

  </ul>

  <p>A @('FOR') @('loop$') expression with just one iteration variable and in
  which the iterative expressions mention no free variable other than the
  iteration variable is called a <i>simple @('loop$')</i> (or, sometimes, a
  <i>simple loop</i>).  An example of a simple loop is</p>

  @({
  (loop$ for x in lst when (evenp x) collect (+ 1 (sq x))).
  })

  <p>A @('FOR') @('loop$') expression is called a <i>fancy @('loop$')</i> if it
  is not simple.  Both of the following @('loop$')s are fancy.</p>

  @({
  (loop$ for x in xlst as y on ylst collect (expr x y))

  (loop$ for x in xlst collect (expr x z))
  })

  <p>The first is fancy because it has two iteration variables, @('x') and
  @('y').  The second is fancy because the body freely uses the variable @('z')
  which is not the iteration variable.</p>

  <p>Now go to @(see lp-section-5) (or return to the <see topic='@(url
  lp-section-0)'>Table of Contents</see>).</p>")

(defxdoc lp-section-5
  :parents (loop$-primer)
  :short "Informal Semantics of @('FOR') @('Loop$')s"
  :long "<h3>LP5: Informal Semantics of @('FOR') @('Loop$')s</h3>

  <p>The value returned by a @('FOR') @('loop$') can be specified as follows
  &mdash; but we hasten to add that this is not how Common Lisp compilers
  implement @('loop$')!  We think this description is easier to understand.</p>

  <p>The first step in evaluating a @('FOR') @('loop$') is to determine the
  range of each iteration variable by evaluating the target expressions as
  previously described.</p>

  <p>Next, repeat the following steps until the process stops.
  (1) If any range is empty, stop.  (2) Otherwise, assign each iteration
  variable the first value in its range and shorten the range by one, by
  removing that first element.  (3) If the <i>until-expr</i> evaluates to
  non-@('nil') under the current values of the global and iteration variables,
  stop.  Otherwise, if the <i>when-expr</i> evaluates to non-@('nil') under the
  current values of the variables, then evaluate the <i>body-expr</i> under the
  current values.  Otherwise, do not evaluate the <i>body-expr</i>.</p>

  <p>When the repetition stops, the <i>body-expr</i> will have been evaluated
  <i>n</i> times, each time producing a value <i>vali</i>, 0 &lt;= <i>i</i> &lt;
  <i>n</i>, where the <i>vali</i> are listed in the order in which they were
  produced.  The result returned by the @('loop$') is determined by the
  operator, <i>op</i>, of the @('loop$') as follows.</p>

  <ul>
  <li>@('SUM') &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&mdash; return the sum of the <i>vali</i></li>
  <li>@('COLLECT') &mdash; return @('(LIST ')<i>val1</i> ... <i>valn</i>@(')')</li>
  <li>@('APPEND') &nbsp; &mdash; return @('(APPEND ')<i>val1</i> ... <i>valn</i>@(')')</li>
  <li>@('ALWAYS') &nbsp; &mdash; return @('(AND ')<i>val1</i> ... <i>valn</i>@(' T)')</li>
  <li>@('THEREIS') &mdash; return @('(OR ')<i>val1</i> ... <i>valn</i>@(')')</li>
  </ul>

  <p>Note that if <i>op</i> is @('ALWAYS'), iteration can stop the first time a
  <i>vali</i> is @('nil').  Similarly, if <i>op</i> is @('THEREIS'), iteration
  can stop the first time a <i>vali</i> is non-@('nil').  Note also that an
  @('ALWAYS') @('loop$') returns @('NIL') or @('T') but a @('THEREIS')
  @('loop$') returns @('nil') or the first non-@('nil') value produced by the
  evaluation of the body.</p>

  <p>Now go to @(see lp-section-6) (or return to the <see topic='@(url
  lp-section-0)'>Table of Contents</see>).</p>")

(defxdoc lp-section-6
  :parents (loop$-primer)
  :short "Challenge Problems about @('FOR') @('Loop$')s"
  :long "<h3>LP6: Challenge Problems about @('FOR') @('Loop$')s</h3>

  <p>The questions below ask you to write and evaluate some @('FOR')
  @('loop$')s at the top-level of ACL2.</p>

  <p>Our answers to the problems in this section are in @(see community-books)
  file @('demos/loop-primer/lp6.lisp').  Feel free to look at our answers after
  you have worked on a problem.  But remember: reading an answer is not as
  helpful as finding it yourself.  If you give up on a problem, look at our
  answer for just that problem, so maybe you take a little more insight into
  your work on subsequent problems.</p>

  <p>Don't forget to start your session by including the standard book for
  @('apply$').</p>

  @({
  (include-book "projects/apply/top" :dir :system)
  })

  <p>Don't bother with adding @(':guard') expressions and don't define any
  functions of your own yet.  All of these questions can be answered by
  @('loop$') expressions involving only ACL2 primitives and the constant
  function @('bags') which we introduce below for convenience.</p>

  <p>Let a &ldquo;bag&rdquo; be a true list of symbols.  The function below returns a
  constant list of bags.  You may use @('(bags)') in your solutions.  Notice
  that some elements of @('(bags)') contain the symbol @('x') and other do
  not.</p>

  @({
  (defun bags ()
    '((a b c)
      (d x e f)
      (g h i x)
      (j)
      (x k l)))
  })

  <p>Here is a sample question and how you might check that your @('loop$')
  computes the expected value.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>Sample Question: Build an alist that pairs the first symbol in every bag
  of @('(bags)') with the number of other symbols in the bag.  The expected
  value is @('((A . 2) (D . 3) (G . 3) (J . 0) (X . 2))').</p>

  <p>Sample Check of a Solution:</p>

  @({
  (equal (loop$ for bag in (bags)
                collect (cons (car bag) (len (cdr bag))))
         '((A . 2) (D . 3) (G . 3) (J . 0) (X . 2)))
  })

  <p>Of course, you could just type the @('loop$') statement at the top-level
  of your ACL2 session and visually inspect the answer.  If you want to
  make a certified book out of your answers we recommend expressing the
  checks as @('defthm') events of @(':rule-classes nil'), as in</p>

  @({
  (defthm check-sample-question
    (equal (loop$ for bag in (bags)
                  collect (cons (car bag) (len (cdr bag))))
           '((A . 2) (D . 3) (G . 3) (J . 0) (X . 2)))
    :rule-classes nil)
  })

  <p>However, if your @('loop$') involves a user-defined function and you
  express your answers as @('defthm')s then each theorem will need to have
  appropriate warrant hypotheses, as illustrated below.</p>

  @({
  (defun my-len (x) (if (atom x) 0 (+ 1 (my-len (cdr x)))))
  (defwarrant my-len)
  (defthm check-my-sample-question
    (implies (warrant my-len)
             (equal (loop$ for bag in (bags)
                           collect (cons (car bag) (my-len (cdr bag))))
                    '((A . 2) (D . 3) (G . 3) (J . 0) (X . 2))))
    :rule-classes nil)
  })

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP6-1:</b> Concatenate all the bags in @('(bags)').</p>

  <p><b>Expected Value:</b>@('(A B C D X E F G H I X J X K L)')</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP6-2:</b> Collect the bags that contain the symbol @('x').</p>

  <p><b>Expected Value:</b>@('((D X E F) (G H I X) (X K L))')</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP6-3:</b> If you used some version of @('member') in your solution to
  LP6-2, now do it without using any version of @('member').</p>

  <p><b>Expected Value:</b>@('((D X E F) (G H I X) (X K L))')</p>

  <p>Don't use any version of @('member') in your answers to the remaining
  questions in this section.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP6-4:</b> Remove all the @('x')s from each bag in @('(bags)') and
  concatenate the resulting bags.</p>

  <p><b>Expected Value:</b>@('(A B C D E F G H I J K L)')</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP6-5:</b> Collect the first symbol of each of the bags in @('(bags)')
  that contains an @('x').</p>

  <p><b>Expected Value:</b>@('(D G X)')</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP6-6:</b> From each bag in @('(bags)'), remove the elements
  preceding the first @('x') and collect the resulting bags.</p>

  <p><b>Expected Value:</b>@('(NIL (X E F) (X) NIL (X K L))')</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP6-7:</b> Let's say the &ldquo;alternating sum of signed squares&rdquo; of a
  list of numbers is the sum of the squares of the elements, except the squares
  of elements in even positions (0-based) are added and the squares in odd
  positions are subtracted.  So the alternating sum of signed squares of @('(1
  2 3 4 5)') is @('(+ 1 -4 9 -16 25)') = @('15').  Compute the alternating sum
  of signed squares of the lengths of the bags in @('(bags)')</p>

  <p><b>Expected Value:</b>@('(+ 9 -16 16 -1 9)') = @('17').</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP6-8:</b> Collect all the function symbols in the current ACL2
  world with an arity greater than 9.</p>

  <p>Three Hints: First, the term @('(function-theory :here)') returns a list
  of the runes of all the @(':logic') mode functions currently in the ACL2
  world.  However, it expands to an expression involving the variable
  @('world') which can be obtained by @('(w state)').  And @(tsee state) may
  not be used in @('FOR') @('loop$')!  So you'll have to @(tsee let) bind
  @('world') to @('(w state)') and write your @('loop$') inside the scope of
  that @('let').</p>

  <p>Second, every @(tsee rune) returned by @('function-theory') is of the form
  @('(:DEFINITION fn . x)'), where @('fn') is the name of a function.</p>

  <p>Third, the arity of a symbol @('fn') is obtained from the world by
  @('(arity fn world)'), except sometimes (for reasons we won't go into!) it
  returns @('nil').</p>

  <p><b>Expected Value:</b> As of ACL2 Version 8.5 (after including the
  @('"projects/apply/top"') book) the answer was @('(MEMOIZE-FORM SEARCH-FN
  SEARCH-FN-GUARD BUILD-STATE1)'), but that may change.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP6-9:</b> Collect the name of every theorem about @('EXPT') in the
  current world.</p>

  <p>Three More Hints: First, the ACL2 world is a list of triples of the form
  @('(name property . val)') representing the current property lists.  In ACL2
  Version 8.5, the length of the world (after including the
  @('"projects/apply/top"') book) is 137,846, so it's too big to just look
  at!</p>

  <p>Second, each event that named a theorem has a triple of the form @('(name
  THEOREM . val)'), where @('name') is the event name and @('val') is the
  translated version of the theorem.  (Thus, you won't find macros like @('+')
  or @('append') in @('val')!  Instead it would contain the function symbols
  appearing in their expansions, e.g., @('binary-+') and @('binary-append').
  But since we're looking for @('expt') and it is not a macro, this doesn't
  matter.)</p>

  <p>Third, the ACL2 term @('(all-fnnames term)') returns a list of all the
  function symbols used in the fully translated term @('term').</p>

  <p><b>Expected Value:</b> As of ACL2 Version 8.5 (after including the
  @('"projects/apply/top"') book) the answer was
  @('(APPLY$-PRIM-META-FN-EV-CONSTRAINT-462 RATIONALP-EXPT-TYPE-PRESCRIPTION
  EXPT-TYPE-PRESCRIPTION-NON-ZERO-BASE)')</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>These exercises highlight three important lessons about
  @('loop$').</p>

  <p>The first is that with @('loop$') you can avoid defining a lot of
  recursive functions.  Imagine doing these same exercises without
  @('loop$').</p>

  <p>The second is that it is not always a good idea to &ldquo;inline&rdquo; @('loop$')s
  instead of defining functions.  The clearest example of that arises above
  when we prohibited you from using @('member')!  Just because @('member') can
  be replaced by a @('loop$') doesn't mean it should be!  @('Member') is an
  exceptionally useful function that enjoys a lot of elegant properties.  By
  introducing the name @('member') and proving its properties we can use it
  conveniently and appeal to those properties often.  Of course, @('member') is
  a Common Lisp primitive, so we're not free to define it, but if we were to
  define a function like that we could use a @('loop$') in its definition.</p>

  <p>Another example of this second lesson is in question LP6-7.  Depending on
  the project at hand, the notion of &ldquo;alternating sum of signed squares&rdquo;
  might be a useful one in its own right.  So perhaps if such a problem came up
  you might define @('(alternating-sum-of-signed-squares lst)'), perhaps using
  @('loop$') in the @('defun'), and then use</p>

  @({
  (alternating-sum-of-signed-squares
    (loop$ for bag in (bags) collect (len bag)))
  })

  <p>to compute the quantity requested in LP6-7.</p>

  <p>The question raised by this second lesson isn't so much whether you use a
  @('loop$') to express the concept but whether you use a @('defun') to give
  the concept a name.  A good rule of thumb is: <i>if the concept has a natural
  name, define it!</i></p>

  <p>Of course, there is the usual trade-off between execution efficiency and
  modularity.  There are various ways to deal with this trade-off in ACL2 but
  since they are not unique to @('loop$') we won't discuss them.</p>

  <p>The third lesson is highlighted by LP6-8 and LP6-9.  @('Loop$') can be
  very useful in extracting data about your current ACL2 session, if you are
  familiar with the ACL2 system-level utilities (see @(see system-utilities)
  for some of them).  Perhaps more relevant is the observation that if you are
  building a big model involving lots of data, you might find @('loop$') handy
  in querying your own data.</p>

  <p>Now go to @(see lp-section-7) (or return to the <see topic='@(url
  lp-section-0)'>Table of Contents</see>).</p>")

(defxdoc lp-section-7
  :parents (loop$-primer)
  :short "Using @('Loop$')s and Guards in @('Defun')s"
  :long "<h3>LP7: Using @('Loop$')s and Guards in @('Defun')s</h3>

  <p>@('Loop$') statements are most efficient when they are guard verified.
  @('Loop$')s typed at the top-level are typically not guard verified and so
  they are not executed by running compiled Common Lisp @('loop')s.  Instead,
  their formal semantics is executed which is akin to saying they are
  interpreted.  But execution efficiency was one of the motivational factors in
  the introduction of @('loop$') and that is best achieved by using @('loop$')s
  in guard verified function definitions.</p>

  <p>Here is an example.  We've already discussed @('member') and the fact that
  calls of @('member') can be replaced by @('loop$')s.  @('Member') is a macro
  that expands logically to @('member-equal'), where</p>

  @({
  (defun member-equal (x lst)
    (declare (xargs :guard (true-listp lst)))
    (cond ((endp lst) nil)
          ((equal x (car lst)) lst)
          (t (member-equal x (cdr lst)))))
  })

  <p>Let's define an equivalent function, named @('member-equal-loop$'), using
  @('loop$').</p>

  @({
  (defun member-equal-loop$ (x lst)
    (declare (xargs :guard (true-listp lst)))
    (loop$ for tail of-type (satisfies true-listp) on lst
           thereis
           (if (equal x (car tail)) tail nil)))

  (defthm member-equal-loop$-is-member-equal
     (equal (member-equal-loop$ x lst)
            (member-equal x lst)))
  })

  <p>Since @('member-equal') has a guard of @('(true-listp lst)'), we will give
  our @('member-equal-loop$') the same guard.  But in our @('loop$') above we
  also wrote that the iteration variable @('tail') satisfies @('true-listp').
  We do that so that ACL2 can prove the guard on @('(car tail)') in the
  @('thereis') clause.  (We could change ACL2 to infer this type for @('tail')
  in this special case, but more generally we would prefer to have an effective
  heuristic for transferring arbitrary properties of @('lst') to relevant
  properties of @('tail').)</p>

  <p>The guard obligations for @('member-equal-loop$') are obscure because we
  haven't explained the formal semantics of @('loop$') yet.  But we do not
  discuss the guard obligations of @('loop$')s in the primer.  If you define a
  function containing a @('loop$') and try to verify its guards the system will
  generate the necessary obligations and try to prove them.  Our solutions to
  all the exercises in this primer can be guard verified automatically.  For
  more details on @('FOR') @('loop$') guards and the guard obligations they generate,
  see @(see for-loop$), specifically, the sections &ldquo;Special Guard Conjectures
  for @('FOR') @('Loop$')s&rdquo; and &ldquo;Discussion of Why @('Loop$')s Have Special
  Guards.&rdquo;</p>

  <p>After admitting @('member-equal-loop$') ACL2 can prove inductively that it is
  equal to @('member-equal').  We'll come back to that later too.</p>

  <p>An alternative way to specify the type of @('tail') would be to add a @(':guard')
  rather than an @('of-type') expression.</p>

  @({
  (defun member-equal-loop$ (x lst)
    (declare (xargs :guard (true-listp lst)))
    (loop$ for tail on lst
           thereis
           :guard (true-listp tail)
           (if (equal x (car tail)) tail nil)))
  })

  <p>The @(':guard') feature of ACL2 is more flexible than @('of-type') because
  guards allow you to use multiple variables to express a constraint, while
  @('of-type') implicitly limits the assertion to the variable being
  introduced.  For example, with a guard you could say @('(subsetp-equal tail
  lst)') while you cannot express such a constraint with @('of-type').
  However, @('of-type') is understood by the Common Lisp compiler which might
  optimize the compiled code using that type information, while guards are not
  seen by the compiler.</p>

  <p>When you use a @('loop$') in a @('defun') to be guard verified, be sure to
  constrain its iteration variables (and global variables) appropriately so you
  can verify the guards of the body.  (You are also allowed to specify
  different guards for any @('when') and @('until') expressions.)  We generally
  split our constraints between @('of-type') and @(':guard') to inform the
  compiler of simple types, while more elaborate guard conditions are sometimes
  necessary to verify the guards of the body, etc.  ACL2 will take any
  @('of-type') information and conjoin it to any @(':guard') when doing guard
  verification.</p>

  <p>Now go to @(see lp-section-8) (or return to the <see topic='@(url
  lp-section-0)'>Table of Contents</see>).</p>")

(defxdoc lp-section-8
  :parents (loop$-primer)
  :short "Challenge Problems about @('FOR') @('Loop$') in @('Defun')s"
  :long "<h3>LP8: Challenge Problems about @('FOR') @('Loop$') in @('Defun')s</h3>

  <p>Do the problems below, starting in a fresh ACL2 session that starts with
  the standard @('(include-book "projects/apply/top" :dir :system)').  Each
  problem starts with one or more recursive functions.  Admit those functions
  in your session.  Then define equivalent versions using @('loop$')s instead
  of recursion.  Make sure each of your @('defun')s is admitted and guard
  verified.  Try to ensure that the @('loop$') version is unconditionally equal
  to the recursive version of each function.  But you might find more elegant
  solutions if you're willing to condition your equivalences on the guards of
  the recursive versions.  After all, a main motivation for using @('loop$') is
  the runtime efficiency of the compiled raw Lisp, and since no ACL2 function
  is executed in raw Lisp unless the guards are verified.</p>

  <p>Finally, you need not use ACL2 to prove that your @('loop$') functions
  correctly implement their recursive counterparts.  But you should be aware
  that with a few exceptions the proofs of our solutions were completely
  automatic.  We'll focus on proving theorems about @('loop$')s later in the
  primer.</p>

  <p>Our answers to the problems in this section are in @(see community-books)
  file @('demos/loop-primer/lp8.lisp').</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>Sample Question:  @('(Sum-vals alist)') sums the value components
  of an alist.  Note its guard.</p>

  @({

  (defun symbol-to-integer-alistp (x)
    (declare (xargs :guard t))
    (if (atom x)
        (equal x nil)
        (and (consp (car x))
             (symbolp (caar x))
             (integerp (cdar x))
             (symbol-to-integer-alistp (cdr x)))))

  (defun sum-vals (alist)
    (declare (xargs :guard (symbol-to-integer-alistp alist)))
    (cond ((endp alist) 0)
          (t (+ (cdar alist) (sum-vals (cdr alist))))))
  })

  <p>E.g., @('(sum-vals '((a . 1) (b . 2) (c . 3))) = 6').</p>

  <p>Define @('sum-vals-loop$') so that it is unconditionally equivalent to
  @('sum-vals') but uses @('loop$') instead of recursion.</p>

  <p>Sample Solution:</p>

  @({
  (defun sum-vals-loop$ (alist)
    (declare (xargs :guard (symbol-to-integer-alistp alist)))
    (loop$ for pair in alist
           sum
           :guard (and (consp pair)
                       (integerp (cdr pair)))
           (cdr pair)))
  })

  <p>The @('(consp pair)') in the @('loop$') @(':guard') is necessary because
  the @('loop$') body contains @('(cdr pair)') and Common Lisp expects @('cdr')
  to be applied to a @('consp') or @('nil').  The @('(integerp (cdr pair))') is
  necessary because the value of the @('loop$') body is being @('sum')med and
  so must be (at least) a number to satisfy Common Lisp's expectation on
  @('+').</p>

  <p>Verification of Sample Solution:</p>

  @({
  (defthm sum-vals-loop$-is-sum-vals
    (equal (sum-vals-loop$ alist)
           (sum-vals alist))
    :rule-classes nil)
  })

  <p>It is conceivable in some Common Lisps that the following would compile
  into more efficient code.</p>

  @({
  (defun sum-vals-loop$ (alist)
    (declare (xargs :guard (symbol-to-integer-alistp alist)))
    (loop$ for pair of-type cons in alist
           sum
           :guard (integerp (cdr pair))
           (the integer (cdr pair))))
  })

  <p>The thinking is that the @('of-type cons') and @('(the integer (cdr
  pair))') could in principle allow the compiler to do type checking that could
  eliminate runtime tests to avoid errors.  That's because @('of-type') and
  @('the') are Common Lisp primitives, as are the particular @(tsee type-spec)s
  used in @('sum-vals-loop$').  Whether such a well-declared version of
  @('sum-vals-loop$') would actually run faster on your Common Lisp depends on
  the compiler and the optimization proclamations.  In CCL and SBCL with ACL2's
  default proclamations, this well-declared version runs no faster than the
  original sample solution does.  We raise this point simply to alert the
  reader to the difference between compiler directives and @(':guard')s.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP8-1</b> Define @('sum-vals-loop$') which is like our solution shown
  for @('sum-vals') above, except instead of using @('symbol-to-integer-alist')
  as the @(':guard') write the @(':guard') as @('(and (true-listp alist) (loop$
  ...))').  Be sure your definition is admitted and guard verified.</p>

  <p>If you want a slightly more challenging problem, omit the @('(true-listp
  alist)') from the @(':guard') and use a @('FOR') @('loop$')
  &ldquo;@('ON')&rdquo; @('alist').  FYI: Common Lisp requires
  &ldquo;@('IN')&rdquo; @('loop$')s to be over a @('true-listp') target, but
  there is no such requirement for &ldquo;@('ON')&rdquo; @('loop$')s.</p>

  <p>You can always convert an &ldquo;@('IN')&rdquo; @('loop$') governed by a
  @('true-listp') check to an &ldquo;@('ON')&rdquo; @('loop$') without the
  check.  See our solutions.  But because of that, we'll use the more elegant
  &ldquo;@('IN')&rdquo; solutions in the rest of these problems.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP8-2</b> The recursive function below is in the ACL2
  sources (therefore, you will not have to define it in your session).  Define
  an equivalent function, named @('arglistp1-loop$') that uses @('loop$')
  instead of recursion.</p>

  @({
  (defun arglistp1 (lst)
    (declare (xargs :guard t))
    (cond ((atom lst) (null lst))
          (t (and (legal-variablep (car lst))
                  (arglistp1 (cdr lst))))))
  })

  <p>Why is @('arglistp1-loop$') a little less efficient than @('arglistp')?</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP8-3</b> The two recursive functions below are used in the ACL2
  sources (thus, you won't have to define them in your session).  Define
  @('packn1-loop$') that is equivalent to @('packn1') but so that it uses
  @('loop$')s and does not mention @('atom-listp').</p>

  @({
  (defun atom-listp (lst)
    (declare (xargs :guard t
                    :mode :logic))
    (cond ((atom lst) (eq lst nil))
          (t (and (atom (car lst))
                  (atom-listp (cdr lst))))))

  (defun packn1 (lst)
    (declare (xargs :guard (atom-listp lst)))
    (cond ((endp lst) nil)
          (t (append (explode-atom (car lst) 10)
                     (packn1 (cdr lst))))))
  })

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;


  <p><b>LP8-4</b>  Define @('select-corresponding-element-loop$') so that it
  is equivalent to @('select-corresponding-element'), below, but using a
  @('loop$') statement.</p>

  @({
  (defun select-corresponding-element (e lst1 lst2)
    (declare (xargs :guard (and (true-listp lst1)
                                (true-listp lst2)
                                (not (member nil lst2)))))
    (cond
     ((endp lst1) nil)
     ((endp lst2) nil)
     ((equal e (car lst1)) (car lst2))
     (t (select-corresponding-element e (cdr lst1) (cdr lst2)))))
  })

  <p>For example,</p>

  @({
  (select-corresponding-element
    'wednesday
    '(sunday monday tueday wednesday thursday friday saturday)
    '(dimanche lundi mardi mercredi jeudi vendredi samedi))
  =
  'MERCREDI
  })

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP8-5</b> Define @('same-mod-wildcard-loop$') to be equivalent to
  @('same-mod-wildcard'), below, but using a @('loop$') statement.</p>

  @({
  (defun same-mod-wildcard (lst1 lst2)
    (declare (xargs :guard (and (true-listp lst1)
                                (true-listp lst2)
                                (equal (len lst1) (len lst2)))))
    (cond ((endp lst1) t)
          ((or (eq (car lst1) '*)
               (eq (car lst2) '*))
           (same-mod-wildcard (cdr lst1) (cdr lst2)))
          ((equal (car lst1) (car lst2))
           (same-mod-wildcard (cdr lst1) (cdr lst2)))
          (t nil)))
  })

  <p>For example,</p>
  @({
  (same-mod-wildcard '(a * c d *) '(a x c * d))
  =
  T
  })

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP8-6</b> The following function is part of the ACL2 source code, so you
  don't have to define it in your session.</p>

  @({
  (defun getprops1 (alist)
    (declare (xargs :guard (true-list-listp alist)))
    (cond ((endp alist) nil)
          ((or (null (cdar alist))
               (eq (car (cdar alist))
                   *acl2-property-unbound*))
           (getprops1 (cdr alist)))
          (t (cons (cons (caar alist) (cadar alist))
                   (getprops1 (cdr alist))))))
  })

  <p>Define @('getprops1-loop$') to do the same thing using @('loop$').</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>Now go to @(see lp-section-9) (or return to the <see topic='@(url
  lp-section-0)'>Table of Contents</see>).</p>")

(defxdoc lp-section-9
  :parents (loop$-primer)
  :short "Semantics of @('FOR') @('Loop$')s"
  :long "<h3>LP9: Semantics of @('FOR') @('Loop$')s</h3>

  <p>For a thorough discussion of the semantics of @('FOR') @('loop$')s see
  @(see for-loop$), specifically the section &ldquo;Semantics&rdquo; which
  includes two subsections, &ldquo;Semantics of Simple @('Loop$')s&rdquo; and
  &ldquo;Semantics of Fancy @('Loop$')s.&rdquo; &ldquo;Fancy&rdquo; @('FOR')
  @('loop$')s are @('FOR') @('loop$')s involving multiple iteration variables
  and/or use of &ldquo;global&rdquo; (i.e., non-iteration) variables in the
  @('loop$') body or the @('until') or @('when') clauses. We discuss @('DO')
  @('loop$')s later.  In this section of the primer we just present some
  examples to drive home a few important points about @('FOR') @('loop$')s,
  namely</p>

  <ul>

  <li>The semantics of a @('loop$') statement is obtained by translating the
  @('loop$') statement, as with the command @(':')@(tsee trans).</li>

  <li>However, translation inserts a lot of tags into the formal term it
  produced.  These tags allow us to execute @('loop$') statements more
  efficiently in the top-level ACL2 read-eval-print @('loop$').  The tags on a
  translated @('loop$'), <i>term</i>, can be removed by the @(':')@(tsee
  tc) (&ldquo;translate and clean&rdquo;) command and its variants @(':tca')
  and @(':tcp').  When we exhibit semantics we typically show these simplified,
  equivalent terms produced by one of these commands.</li>

  <li>The semantics of @('FOR') @('loop$')s look quite different from the
  semantics of @('DO') @('loop$')s.  Furthermore, the semantics of simple
  @('loop$')s have a different form than those of fancy @('loop$').  So
  &ldquo;minor&rdquo; changes in the syntax of a @('loop$') statement &mdash; the
  addition of an @('AS') clause, the use of global variable in the body of the
  @('loop$'), or the use of @('DO') instead of, say, @('collect') &mdash; can
  cause radical changes in the form of the semantics.</li>

  <li>The semantics of @('loop$')s always involve calls of @(tsee scion)s on
  lambda objects derived from the @('when'), @('until'), and @('loop$') body
  clauses.  The scions for simple @('FOR') @('loop$')s are @('sum$'),
  @('collect$'), @('always$'), @('thereis$'), @('append$'), @('until$'), and
  @('when$'); the scions for fancy @('FOR') @('loop$')s are @('sum$+'),
  @('collect$+'), @('always$+'), @('thereis$+'), @('append$+'), @('until$+'),
  and @('when$+'); and the scion for @('DO') @('loop$')s is @('do$').</li>

  <li>The iteration variables become formals of the @('lambda') objects and
  standard names are used in place of the user's names.</li>

  </ul>

  <p>Now we drive home these points with some examples.  The <see topic='@(url
  lp-section-10)'>next section</see> elaborates further.</p>

  <p>Here is the full, formal translation of a simple @('FOR') @('loop$').</p>

  @({
  ACL2 !>:trans (loop$ for x of-type integer in lst
                       when (evenp x)
                       collect (* x x))

  (RETURN-LAST
   'PROGN
   '(LOOP$ FOR X OF-TYPE INTEGER IN LST
           WHEN (EVENP X)
           COLLECT (* X X))
   (COLLECT$
     '(LAMBDA (LOOP$-IVAR)
              (DECLARE (TYPE INTEGER LOOP$-IVAR)
                       (XARGS :GUARD (INTEGERP LOOP$-IVAR)
                              :SPLIT-TYPES T)
                       (IGNORABLE LOOP$-IVAR))
              (RETURN-LAST 'PROGN
                           '(LAMBDA$ (LOOP$-IVAR)
                                     (DECLARE (TYPE INTEGER LOOP$-IVAR))
                                     (LET ((X LOOP$-IVAR))
                                          (DECLARE (IGNORABLE X))
                                          (* X X)))
                           ((LAMBDA (X) (BINARY-* X X))
                            LOOP$-IVAR)))
     (WHEN$ '(LAMBDA (LOOP$-IVAR)
                     (DECLARE (TYPE INTEGER LOOP$-IVAR)
                              (XARGS :GUARD (INTEGERP LOOP$-IVAR)
                                     :SPLIT-TYPES T)
                              (IGNORABLE LOOP$-IVAR))
                     (RETURN-LAST 'PROGN
                                  '(LAMBDA$ (LOOP$-IVAR)
                                            (DECLARE (TYPE INTEGER LOOP$-IVAR))
                                            (LET ((X LOOP$-IVAR))
                                                 (DECLARE (IGNORABLE X))
                                                 (EVENP X)))
                                  ((LAMBDA (X) (EVENP X)) LOOP$-IVAR)))
            LST)))
  })

  <p>However, the logical meaning of this is easier to understand by
  looking at one of the @('tc') variations.</p>

  @({
  ACL2 !>:tc (loop$ for x of-type integer in lst
                        when (evenp x)
                        collect (* x x))
   (COLLECT$ '(LAMBDA (LOOP$-IVAR)
                      (BINARY-* LOOP$-IVAR LOOP$-IVAR))
             (WHEN$ '(LAMBDA (LOOP$-IVAR) (EVENP LOOP$-IVAR))
                    LST))
  ACL2 !>:tcp (loop$ for x of-type integer in lst
                         when (evenp x)
                         collect (* x x))
   (COLLECT$ (LAMBDA$ (LOOP$-IVAR)
                      (* LOOP$-IVAR LOOP$-IVAR))
             (WHEN$ (LAMBDA$ (LOOP$-IVAR)
                             (EVENP LOOP$-IVAR))
                    LST))
  ACL2 !>:tca (loop$ for x of-type integer in lst
                         when (evenp x)
                         collect (* x x))
   (PROG2$
     '(LOOP$ FOR X OF-TYPE INTEGER IN LST
             WHEN (EVENP X)
             COLLECT (* X X))
     (COLLECT$ (LAMBDA$ (LOOP$-IVAR)
                  (DECLARE (TYPE INTEGER LOOP$-IVAR)
                           (XARGS :GUARD (INTEGERP LOOP$-IVAR)
                                  :SPLIT-TYPES T))
                  (LET ((X LOOP$-IVAR))
                       (* X X)))
               (WHEN$ (LAMBDA$ (LOOP$-IVAR)
                         (DECLARE (TYPE INTEGER LOOP$-IVAR)
                                  (XARGS :GUARD (INTEGERP LOOP$-IVAR)
                                         :SPLIT-TYPES T))
                         (LET ((X LOOP$-IVAR))
                              (EVENP X)))
                      LST)))
  })

  <p>Note that @(':tc') prints the term generated by translating the @('loop$')
  and then removing all tags.  The guard and type declarations are logically
  irrelevant.  What you see is what the theorem prover will see
  (if all the necessary warrants are assumed) before it starts to rewrite the
  term.  Note that the @('lambda') object is just a quoted list constant and
  the body has been translated so that the @('*') macro was expanded in terms
  of @('binary-*').</p>

  <p>@(':Tcp') (&ldquo;p&rdquo; for &ldquo;pretty&rdquo;) introduces familiar system macros.</p>

  <p>@(':Tca') (&ldquo;a&rdquo; for &ldquo;annotations&rdquo;) includes the original @('loop$')
  statement and shows declarations (if any) and the correspondence between the
  user's iteration variable (@('x') here) and the formal variable used in the
  @('lambda') objects generated (@('loop$-ivar') here).</p>

  <p>The translation of @('loop$') bodies into @('lambda') objects standardizes
  the variable name, either as @('loop$-ivar') for simple @('loop$')s which
  have just one iteration variable, or as @('loop$-gvars') and @('loop$-ivars')
  for fancy @('loop$')s which may have one or more global variables and one or
  more iteration variables.  We'll deal with fancy @('loop$')s immediately
  below, but values are passed for @('loop$-gvars') and @('loop$-ivars') as tuples
  listing all the global values and all the current iteration variable
  values.</p>

  <p>The advantage of this standardization is that choosing different names for
  the iteration variables does not affect the formal semantics.</p>

  <p>However, if we make a simple syntactic change, like introducing a global
  variable by changing the body of the loop$ from @('(* x x)') to @('(* x a)'),
  where @('a') is not an iteration variable, we drastically change the
  semantics because we've converted the simple @('loop$') into a fancy
  @('loop$').  The (clean and pretty) semantics of</p>

  @({
  (loop$ for x in lst when (evenp x) collect (* x a))
  })

  <p>is</p>

  @({
  (COLLECT$+ (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS)
                      (* (CAR LOOP$-IVARS) (CAR LOOP$-GVARS)))
             (LIST A)
             (WHEN$+ (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS)
                              (EVENP (CAR LOOP$-IVARS)))
                     NIL
                     (LOOP$-AS (LIST LST))))
  })

  <p>The annotated semantics of that @('loop$') is</p>

  @({
  (PROG2$
   '(LOOP$ FOR X IN LST
           WHEN (EVENP X)
           COLLECT (* X A))
   (COLLECT$+
     (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS)
              (DECLARE (XARGS :GUARD (AND (TRUE-LISTP LOOP$-GVARS)
                                          (EQUAL (LEN LOOP$-GVARS) 1)
                                          (TRUE-LISTP LOOP$-IVARS)
                                          (EQUAL (LEN LOOP$-IVARS) 1))
                              :SPLIT-TYPES T))
              (LET ((A (CAR LOOP$-GVARS))
                    (X (CAR LOOP$-IVARS)))
                   (* X A)))
     (LIST A)
     (WHEN$+ (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS)
                      (DECLARE (XARGS :GUARD (AND (TRUE-LISTP LOOP$-GVARS)
                                                  (EQUAL (LEN LOOP$-GVARS) 0)
                                                  (TRUE-LISTP LOOP$-IVARS)
                                                  (EQUAL (LEN LOOP$-IVARS) 1))
                                      :SPLIT-TYPES T))
                      (LET ((X (CAR LOOP$-IVARS)))
                           (EVENP X)))
             NIL
             (LOOP$-AS (LIST LST)))))
  })

  <p>Logically, we could have typed either of the above terms instead of the
  fancy @('loop$').  But operationally, the @('loop$') executes faster (when
  guards are verified).</p>

  <p>Notice that the simple scions @('COLLECT$') and @('WHEN$') have been
  replaced by their fancy counterparts, @('COLLECT$+') and @('WHEN$+').  The
  @('lambda') objects now have two formals, one for holding a tuple containing
  all of the global variable values and one for a tuple holding all of the
  current iteration variable values.  The global variable value tuple, @('(LIST
  A)'), is passed into the fancy scions if the corresponding @('lambda') object
  uses globals (as for the @('collect$+') but not for the @('when$+')
  @('lambda') where @('NIL') is passed instead).  The list over which the
  iteration variable ranges, @('LST'), is now a list of tuples constructed by
  @('LOOP$-AS').  Finally, the bodies of the @('lambda')s now access the
  relevant values with @('CAR') and @('CDR') nests around the global and
  iteration tuples. (No @('CDR')s appear above because there is only one global
  and one iteration variable in this example.)</p>

  <p>The following similar but still fancier @('loop$') illustrates the general
  situation.  This @('loop$') has two iteration variables, @('x') and @('y')
  taking on values from two ranges, @('xlst'), and @('ylst'), and uses two
  global variables, @('a') and @('b'), in the body.  We've added comments to
  name the components of the two tuples.</p>

  @({
  ACL2 !>:tcp (loop$ for x in xlst
                     as  y in ylst
                     when (evenp x)
                     collect (* x y a b))
   (COLLECT$+ (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS)
                       (* (CAR LOOP$-IVARS)               ; x
                          (CADR LOOP$-IVARS)              ; y
                          (CAR LOOP$-GVARS)               ; a
                          (CADR LOOP$-GVARS)))            ; b
              (LIST A B)
              (WHEN$+ (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS)
                               (EVENP (CAR LOOP$-IVARS))) ; x
                      NIL
                      (LOOP$-AS (LIST XLST YLST))))
  })

  <p>Notice how the bodies of the @('lambda') objects now use components of the
  @('loop$-gvars') and @('loop$-ivars)') for the current values of the global
  variables @('a') and @('b') and the iteration variables @('x') and @('y').
  The values of @('x') and @('y') are corresponding elements of @('xlst') and
  @('ylst') as grouped together by @('(loop$-as (list xlst ylst))').</p>

  <p>For a still-more elaborate @('FOR') @('loop$') and a step-by-step
  description of how the value of the formal semantics is computed, go to @(see
  lp-section-10).</p>

  <p>Now go to @(see lp-section-10) (or return to the <see topic='@(url
  lp-section-0)'>Table of Contents</see>).</p>")

(defxdoc lp-section-10
  :parents (loop$-primer)
  :short "The Evaluation of the Formal Semantics of a Fancy @('Loop$')"
  :long "<h3>LP10: The Evaluation of the Formal Semantics of a Fancy @('Loop$')</h3>

  <p>Below we show the evaluation of a fancy @('loop$') that uses the function
  @('packn') to create a list of symbols.  We start with an example of
  @('packn') so you can infer its behavior.  But our real interest is the
  behavior of the @('loop$').</p>

  @({
  ACL2 !>(packn (list 'R2 '- 'D 2))
  R2-D2
  ACL2 !>(let ((mark '*))
           (loop$ for x in '(a * b c d e * f g h i j * k)
                  as  y in '(u v * w * u v * x y z)
                  as  i from 0 to 100 by 3
                  when (and (evenp i)
                            (not (eq x mark))
                            (not (eq y mark)))
                  collect (packn (list x y '_ i))))
  (AU_0 GX_24 IZ_30)
  ACL2 !>
  })

  <p>We now explain carefully the evaluation of the @('loop$') expression above
  in an environment in which @('mark') is bound to the asterisk symbol,
  @('*').</p>

  <p>The first three lines of the @('loop$') introduce the so-called <i>iteration
  variables</i>, @('x'), @('y'), and @('i'), and their respective
  <i>ranges</i>.</p>

  <p>The @('when') clause specifies a predicate on the iteration variables,
  identifying the &ldquo;good&rdquo; cases, i.e., the values of the iteration variables
  that we care about.  However, note that the predicate above mentions the
  variable @('mark'), which is not one of the iteration variables.  We call
  such variables <i>globals</i> because their values are not set within the
  scope of the @('loop').</p>

  <p>The @('collect') clause specifies an expression to be evaluated on the
  &ldquo;good&rdquo; iteration variable values and collects the results of those
  evaluations.</p>

  <p>If you replace the symbol @('loop$') above by @('loop') you get a legal
  Common Lisp @('loop') expression with the same value (if executed when
  @('mark') is bound to @('*')).</p>

  <p>For our purposes, the easiest way to think about this particular statement
  is to decompose it into three steps.</p>

  <p>Step 1: The lines introducing the iteration variables and their ranges
  cause us to make a table of corresponding values of @('x'), @('y'), and
  @('i'), as shown below in the form of a list of triples.  This list is as
  long as the shortest individual range.</p>

  @({
  ; x y  i
  ((A U  0)
   (* V  3)
   (B *  6)
   (C W  9)
   (D * 12)
   (E U 15)
   (* V 18)
   (F * 21)
   (G X 24)
   (H Y 27)
   (I Z 30)).
  })

  <p>Step 2: the @('when') clause maps over the above table and identifies the
  entries as &ldquo;good&rdquo; or &ldquo;bad&rdquo;, where the good ones have an even value for
  @('i') and values for @('x') and @('y') that are not the asterisk mark,
  @('*').  We annotate the table accordingly below.</p>

  @({
  ; x y  i
  ((A U  0)        ; GOOD!
   (* V  3)        ; bad: odd i (and asterisk)
   (B *  6)        ; bad: asterisk
   (C W  9)        ; bad: odd i
   (D * 12)        ; bad: asterisk
   (E U 15)        ; bad: odd i
   (* V 18)        ; bad: asterisk
   (F * 21)        ; bad: odd i (and asterisk)
   (G X 24)        ; GOOD!
   (H Y 27)        ; bad: odd i
   (I Z 30)).      ; GOOD!
  })

  <p>Effectively the @('when') clause pares down the table to just the good
  entries.</p>

  @({
  ; x y  i
  ((A U  0)        ; GOOD!
   (G X 24)        ; GOOD!
   (I Z 30)).      ; GOOD!
  })

  <p>Step 3: the @('collect') clause maps over pared-down table, evaluating and
  collecting the results of @('(packn (list x y '_ i))') for each triple in the
  table.</p>

  @({
  (AU_0
   GX_24
   IZ_30).
  })

  <p>The ACL2 semantics of the @('loop$') statement reflects this understanding
  of the statement.  (The display below is the output of @(':tca') on the
  @('loop$'), but with the @('DECLARE') forms deleted and the three comments
  added.)</p>

  @({
  (collect$+                                        ; step 3
   (lambda$ (loop$-gvars loop$-ivars)
            (let ((x (car loop$-ivars))
                  (y (cadr loop$-ivars))
                  (i (caddr loop$-ivars)))
              (packn (list x y '_ i))))
   nil
   (when$+                                          ; step 2
    (lambda$ (loop$-gvars loop$-ivars)
             (let ((mark (car loop$-gvars))
                   (x (car loop$-ivars))
                   (y (cadr loop$-ivars))
                   (i (caddr loop$-ivars)))
               (and (evenp i)
                    (not (eq x mark))
		    (not (eq y mark)))))
    (list mark)
    (loop$-as (list '(a * b c d e * f g h i j * k)  ; step 1
                    '(u v * w * u v * x y z)
                    (from-to-by 0 100 3)))))
  })

  <p>In step 1, the @('loop$-as') function takes a list of the individual
  ranges and builds the first version of the iteration variable table.  The
  function @('from-to-by') just enumerates the integers from its first argument
  to its second argument in steps of size given by its third argument.</p>

  <p>In step 2, the @('when$+') function takes three arguments.  Note that the
  last argument of the @('when$+') function is the iteration variable table
  computed by step 1.  The first argument of the @('when$+') function is a
  @('lambda$') expression representing the predicate used to identify the
  &ldquo;good&rdquo; entries.  But that predicate may also require the value of any
  global variables used.  So the @('lambda$') expression has two arguments,
  @('loop$-gvars'), the list of values of the global variables, and
  @('loop$-ivars'), a tuple of values corresponding to a line in the iteration
  variable table.  The middle argument of the @('when$+') provides the values
  of the global variables and, as noted earlier, the last argument is the
  iteration variable table.  The @('when$+') maps over the iteration variable
  table and collects the &ldquo;good&rdquo; lines, returning them as a list.</p>

  <p>In step 3, the @('collect$+') takes three arguments.  The first is a
  @('lambda$') expression on the @('loop$-gvars') and @('loop$-ivars') as
  above.  The second and third arguments are the global variable values and the
  &ldquo;good&rdquo; lines from the pared-down iteration variable table as computed by
  step 2.  Note that since the @('collect') clause does not mention any global
  variables the global variable tuple in the second argument of the
  @('collect$+') is @('nil').</p>

  <p>Of course, Common Lisp does not decompose the corresponding @('loop')
  statement this way but generates much more efficient compiled code.</p>

  <p>The ACL2 semantics is rendered compositionally to make it easier to reason
  about @('loop$') statements.  If the guards of the @('loop$') statement
  &mdash; which we haven't discussed yet &mdash; are verified then the ACL2
  loop$ statement is rendered into the corresponding Common Lisp @('loop')
  statement, compiled, and efficiently executed.</p>

  <p>Now go to @(see lp-section-11) (or return to the <see topic='@(url
  lp-section-0)'>Table of Contents</see>).</p>")

(defxdoc lp-section-11
  :parents (loop$-primer)
  :short "Proving Theorems about @('FOR') @('Loop$')s"
  :long "<h3>LP11: Proving Theorems about @('FOR') @('Loop$')s</h3>

  <p>Proving theorems about @('FOR') @('loop$') in ACL2 is essentially no
  different than proving theorems about other constructs in ACL2.  Indeed,
  since @('loop$')s turn into calls of @(see scion)s of @(tsee apply$), proving
  things about them is exactly the problem of proving things about scions.
  However, @('loop$')s raise some problems that are not fully technical.</p>

  <ul>

  <li>Iteration is so common in programming &mdash; and the meaning of
  @('loop$') statements are intuitively obvious &mdash; that you often don't
  think anything logically complicated is going on!  But when proofs are
  desired you must keep induction in mind and you must train yourself to see
  the need for generalization in order to allow the necessary inductions.</li>

  <li>You're not syntactically aware of the presence of @('apply$') and the
  concomitant need for @(see tame)ness and @(see warrant)s.</li>

  <li>You don't see the translations of @('loop$')s when you type them but they
  appear &ldquo;unexpectedly&rdquo; in the checkpoints of failing proofs and that can
  throw you for a loop (so to speak).</li>

  <li>The translations of @('loop$')s, especially of fancy @('loop$'), are
  pretty complicated in and of themselves and can be difficult to understand,
  much less generalize and manipulate formally.</li>

  <li>The ACL2 user rarely has to think about local variable bindings, but
  those issues arise quite often in dealing with loop$s (and nested @('lambda')
  objects in general).</li>

  </ul>

  <p>With these points in mind we will now work through a proof about a fancy
  @('loop$').  In the next section we'll challenge you to do some proofs about
  other @('loop$')s.  The proof description below is rather long because we
  cast it as a narrative of the proof discovery process and the actual
  chronology of events submitted, including failed events and our thoughts
  about the failures.</p>

  <p>Sample Question: Define the function @('all-pairs') recursively so that
  @('(all-pairs imax jmax)') creates a list of all pairs @('(i . j)') where
  @('1 <= i <= imax') and @('1 <= j <= jmax').  Then define the @('loop$')
  version of @('all-pairs') and prove it is equivalent to @('all-pairs').
  Both versions must be guard verified.</p>

  <p>Sample Solution (as a narrative of the discovery).</p>

  <p>As usual, we make sure we're operating in a session where</p>

  @({(include-book "projects/apply/top" :dir :system)})

  <p>We will construct our pairs with</p>

  @({
  (defun make-pair (i j)
    (declare (xargs :guard t))
    (cons i j))
  })

  <p>Here is our recursive definition.  It involves two helper functions.
  @('All-pairs-helper2') keeps @('i') fixed and runs @('j') from @('1') to
  @('jmax') to compute the list of pairs @('((i . 1) (i . 2) ... (i . jmax))').
  @('All-pairs-helper1') just calls the former helper for each @('i') from
  @('1') to @('imax') and appends the lists together.  The top-level
  @('all-pairs') calls @('all-pairs-helper1') with @('i') properly initialized
  to @('1').</p>

  @({
  (defun all-pairs-helper2 (i j jmax)
    (declare (xargs :measure (nfix (- (+ (nfix jmax) 1) (nfix j)))
                    :guard (and (natp i) (natp j) (natp jmax))))
    (let ((j (nfix j))
          (jmax (nfix jmax)))
      (cond
       ((> j jmax) nil)
       (t (cons (make-pair i j)
                (all-pairs-helper2 i (+ 1 j) jmax))))))

  (defun all-pairs-helper1 (i imax jmax)
    (declare (xargs :measure (nfix (- (+ (nfix imax) 1) (nfix i)))
                    :guard (and (natp i) (natp imax) (natp jmax))))
    (let ((i (nfix i))
          (imax (nfix imax)))
      (cond
       ((> i imax) nil)
       (t (append (all-pairs-helper2 i 1 jmax)
                  (all-pairs-helper1 (+ 1 i) imax jmax))))))

  (defun all-pairs (imax jmax)
    (declare (xargs :guard (and (natp imax) (natp jmax))))
    (all-pairs-helper1 1 imax jmax))
  })

  <p>Here is a simple test.</p>

  @({
  ACL2 !>(all-pairs 2 4)
  ((1 . 1)
   (1 . 2)
   (1 . 3)
   (1 . 4)
   (2 . 1)
   (2 . 2)
   (2 . 3)
   (2 . 4))
  })

  <p>And here is our first attempt to define the @('loop$') version, which is
  considerably &ldquo;simpler&rdquo; (or, at least, shorter).  But this will fail!  Can
  you say why without reading the error message?</p>

  @({
  (defun all-pairs-loop$ (imax jmax)
    (declare (xargs :guard (and (natp imax) (natp jmax))))
    (loop$ for i from 1 to imax
           append
           (loop$ for j from 1 to jmax
                  collect (make-pair i j))))

  ACL2 Error [Translate] in ( DEFUN ALL-PAIRS-LOOP$ ...):  The body of
  a LAMBDA object, lambda$ term, or loop$ statement should be fully badged
  but MAKE-PAIR is used in
  ((LAMBDA (I J) (MAKE-PAIR I J)) (CAR LOOP$-GVARS) (CAR LOOP$-IVARS))
  and has no badge. ...
  ... Note:  this error occurred in the context
  (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS)
           (DECLARE (XARGS :GUARD (AND (TRUE-LISTP LOOP$-GVARS)
                                       (EQUAL # 1)
                                       (TRUE-LISTP LOOP$-IVARS)
                                      (EQUAL # 1))))
           (LET ((I (CAR LOOP$-GVARS))
                 (J (CAR LOOP$-IVARS)))
                (DECLARE (IGNORABLE I J))
                (MAKE-PAIR I J))).
  })

  <p>The error message above includes some extraneous possible explanation of
  the error which we've omitted.</p>

  <p>The error tells us we forgot to assign a badge to @('make-pair').  We
  could call @('(defbadge make-pair)') at this point.  But since we intend to
  prove things about @('all-pairs-loop$') we'll actually need the warrant for
  the @('make-pair'), since @('make-pair') is user-defined and is used in the body of a
  @('loop$').  So we'll go ahead and create the warrant.</p>

  @({
  (defwarrant make-pair)
  })

  <p>(Had we just badged @('make-pair') at this point and proceeded another
  error message would crop up in due course and tell us to warrant it.)</p>

  <p>Trying the @('defun') again causes another failure with the checkpoint
  shown below.</p>

  @({
  (defun all-pairs-loop$ (imax jmax)
    (declare (xargs :guard (and (natp imax) (natp jmax))))
    (loop$ for i from 1 to imax
           append
           (loop$ for j from 1 to jmax
                  collect (make-pair i j))))

  *** Key checkpoint at the top level: ***

  Subgoal 1.2'
  (IMPLIES (AND (CONSP LOOP$-IVARS)
                (NOT (CDR LOOP$-IVARS))
                (CONSP LOOP$-GVARS)
                (NOT (CDR LOOP$-GVARS)))
           (INTEGERP (CAR LOOP$-GVARS)))

  ACL2 Error [Failure] in ( DEFUN ALL-PAIRS-LOOP$ ...):  The proof of
  the guard conjecture for ALL-PAIRS-LOOP$ has failed; see the discussion
  above about :VERIFY-GUARDS and :GUARD-DEBUG.  See :DOC failure.
  })

  <p>We need to prove, as part of the guard verification, that @('(CAR
  LOOP$-GVARS)') is an integer.  At this point we might want to refresh our
  idea of what the formal semantics of that nested loop$ is!</p>

  <p>We do not recommend using @(':trans') for that refreshment!  You can try
  it and you'll see 67 lines of output with a lot of extra stuff in it used to
  help evaluate such forms efficiently.  Instead we'll use
  @(':tca') (&ldquo;translate, clean, and annotate&rdquo;) which produces about half as
  much output and shows the original form of each @('loop$') together with
  formal semantics, complete with @(':guard') declarations on the @('LAMBDA')
  objects and correspondences between the variable names used in the original
  statement with the components of the formals @('LOOP$-GVARS') and
  @('LOOP$-IVARS') in the @('lambda$') terms generated.</p>

  <p>(Note: We have manually inserted some comments to identify certain lines
  of the display below.)</p>

  @({
  ACL2 !>:tca (loop$ for i from 1 to imax
                     append
                     (loop$ for j from 1 to jmax
                            collect (make-pair i j)))
  (PROG2$
    '(LOOP$ FOR I FROM 1 TO IMAX
            APPEND
            (LOOP$ FOR J FROM 1 TO JMAX
                   COLLECT (MAKE-PAIR I J)))
    (APPEND$+                                                      ; [0]
     (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS)                            ; [1]
       (DECLARE (XARGS :GUARD (AND (TRUE-LISTP LOOP$-GVARS)        ; [2]
                                   (EQUAL (LEN LOOP$-GVARS) 1)
                                   (TRUE-LISTP LOOP$-IVARS)
                                   (EQUAL (LEN LOOP$-IVARS) 1))
                       :SPLIT-TYPES T))
       (LET ((JMAX (CAR LOOP$-GVARS))                              ; [3]
             (I (CAR LOOP$-IVARS)))
         (PROG2$
          '(LOOP$ FOR J FROM 1 TO JMAX COLLECT (MAKE-PAIR I J))
          (COLLECT$+
           (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS)
             (DECLARE (XARGS :GUARD (AND (TRUE-LISTP LOOP$-GVARS)
                                         (EQUAL (LEN LOOP$-GVARS) 1)
                                         (TRUE-LISTP LOOP$-IVARS)
                                         (EQUAL (LEN LOOP$-IVARS) 1))
                             :SPLIT-TYPES T))
             (LET ((I (CAR LOOP$-GVARS))
                   (J (CAR LOOP$-IVARS)))
               (MAKE-PAIR I J)))
           (LIST I)
           (LOOP$-AS (LIST (FROM-TO-BY 1 JMAX 1)))))))             ; [4]
     (LIST JMAX)                                                   ; [5]
     (LOOP$-AS (LIST (FROM-TO-BY 1 IMAX 1)))))                     ; [6]
  })

  <p>We're trying to verify the guards all the functions in that expression,
  and we have the @(':guard') in the @('defun') of @('all-pairs-loop$') to work
  with.  That @(':guard') is @('(and (natp imax) (natp jmax))').</p>

  <p>So what functions above require an argument to be an integer?  Hint: There
  is only one such function but it occurs in two places.</p>

  <p>@('From-to-by') requires all three of its arguments to be integers and
  that function appears on lines [4] and [6].  Line [4] requires @('jmax') to
  be an integer and line [6] requires @('imax') to be an integer.  But line [6]
  is the formal term representing the &ldquo;@('from 1 to imax')&rdquo; range of the
  @('append') @('loop$') formalized with the fancy scion @('APPEND$+') at line
  [0].  That @('imax') is literally the first formal variable of the defun of
  @('all-pairs-loop$') whose @(':guard') says @('imax') and @('jmax') are a
  naturals.  So [6] is not the problem.</p>

  <p>The @('jmax') in line [4], on the other hand, is actually a @('let')-bound
  variable (see line [3]) within the @('lambda') object (line [1]) that is the
  body of the @('append') loop$ [line 0].  @('jmax') is bound inside that
  @('lambda') on line [3] to @('(car loop$-gvars)') and the @(':guard') (line
  [2]) of that @('lambda') does not require @('(car loop$-gvars)') to be an
  integer.  We need to add that requirement to [2].</p>

  <p>So how do we change the @(':guard') of a @('lambda') generated by the
  translation of the @('append') @('loop$')?  We add &ldquo;@(':guard (natp
  jmax)')&rdquo; after the @('append') operator.  (Note that @('(integerp jmax)')
  would suffice here but we added the stronger condition ensured by the
  @('all-pairs-loop$')'s guard.)</p>

  <p>Using @(':tca') again on the modified @('loop$') confirms our change.</p>

  @({
  ACL2 !>:tca (loop$ for i from 1 to imax
                          append
                          :guard (natp jmax)                   ; [new]
                          (loop$ for j from 1 to jmax
                                 collect (make-pair i j)))
  (PROG2$
    '(LOOP$ FOR I FROM 1 TO IMAX
            APPEND
            (LOOP$ FOR J FROM 1 TO JMAX
                   COLLECT (MAKE-PAIR I J)))
    (APPEND$+                                                  ; [0]
     (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS)                        ; [1]
       (DECLARE (XARGS :GUARD (AND (TRUE-LISTP LOOP$-GVARS)    ; [2']
                                   (EQUAL (LEN LOOP$-GVARS) 1)
                                   (TRUE-LISTP LOOP$-IVARS)
                                   (EQUAL (LEN LOOP$-IVARS) 1)
                                   (NATP (CAR LOOP$-GVARS)))   ; [new]
                       :SPLIT-TYPES T))
       (LET ((JMAX (CAR LOOP$-GVARS))                          ; [3]
             (I (CAR LOOP$-IVARS)))
         (PROG2$
          '(LOOP$ FOR J FROM 1 TO JMAX COLLECT (MAKE-PAIR I J))
          (COLLECT$+
           (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS)
             (DECLARE (XARGS :GUARD (AND (TRUE-LISTP LOOP$-GVARS)
                                         (EQUAL (LEN LOOP$-GVARS) 1)
                                         (TRUE-LISTP LOOP$-IVARS)
                                         (EQUAL (LEN LOOP$-IVARS) 1))
                             :SPLIT-TYPES T))
             (LET ((I (CAR LOOP$-GVARS))
                   (J (CAR LOOP$-IVARS)))
               (MAKE-PAIR I J)))
           (LIST I)
           (LOOP$-AS (LIST (FROM-TO-BY 1 JMAX 1)))))))         ; [4]
     (LIST JMAX)                                               ; [5]
     (LOOP$-AS (LIST (FROM-TO-BY 1 IMAX 1)))))                 ; [6]
  })

  <p>Observe the difference between the @(':guard') on the original line [2]
  and the @(':guard') on the new line [2'].  The latter includes @('(natp (car
  loop$-gvars))').</p>

  <p>If we think in terms of scions, we're saying &ldquo;Every time this @('lambda')
  object is applied, its two formals must satisfy the conjunction beginning at
  line [2'].&rdquo;</p>

  <p>Finally, how do we know every application of the @('lambda') by the fancy
  scion @('append$+') (line [0]) will satisfy this guard?  We know from the
  definition of @('append$+') that every application supplies the @('(list
  jmax)') from line [5] as the value of @('loop$-gvars').  That occurrence of
  @('jmax') is at the top-level of the body and in the scope of the guard of
  @('all-pairs-loop$'), which says @('jmax') is a natural.  So the guards can
  be proved now.</p>

  <p>So now we can admit and verify the guards of our @('loop$') version of
  @('all-pairs').</p>

  @({
  (defun all-pairs-loop$ (imax jmax)
    (declare (xargs :guard (and (natp imax) (natp jmax))))
    (loop$ for i from 1 to imax
           append
           :guard (natp jmax)
           (loop$ for j from 1 to jmax
                  collect (make-pair i j))))
  })

  <p>Our goal is to prove the theorem below.  We use @(see The-Method), with
  which we assume you're familiar but which we narrate below.</p>

  <p>First we try to prove our main goal.  It fails with the checkpoint
  shown.</p>

  @({
  (defthm main
    (implies (and (natp imax)
                  (natp jmax))
             (equal (all-pairs-loop$ imax jmax)
                    (all-pairs imax jmax))))

  *** Key checkpoint at the top level: ***

  Goal''
  (IMPLIES
   (AND (INTEGERP IMAX)
        (<= 0 IMAX)
        (INTEGERP JMAX)
        (<= 0 JMAX))
   (EQUAL
    (APPEND$+
     (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS)
              (COLLECT$+ (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS)
                                  (CONS (CAR LOOP$-GVARS)
                                        (CAR LOOP$-IVARS)))
                         (LIST (CAR LOOP$-IVARS))
                         (LOOP$-AS (LIST (FROM-TO-BY 1 (CAR LOOP$-GVARS) 1)))))
     (LIST JMAX)
     (LOOP$-AS (LIST (FROM-TO-BY 1 IMAX 1))))
    (ALL-PAIRS-HELPER1 1 IMAX JMAX)))
  })

  <p>Looking at the conclusion we see need to prove that the @('append$+') term
  is equal to the @('all-pairs-helper1') term.  From our ACL2 experience with
  recursive functions like @('all-pairs-helper1') we know this is an inductive
  proof.  But no induction is suggested by @('(all-pairs-helper1 1 imax jmax)')
  because the constant @('1') is in a controller position.  We need to
  generalize the @('1') by replacing it with @('i0'), a general initial value
  of @('i').  Note that we replace the @('1') in two places, namely, the first
  @('1') in @('(loop$-as (list (from-to-by 1 imax 1)))'), and the @('1') in
  @('(all-pairs-helper1 1 imax jmax)').  Those two @('1')s are the concrete
  initial values of two @('i') counters on opposite sides of the equality.
  There are three other occurrences of the number @('1') in the conjecture.
  The first one is the initial value of the variable @('j'), the second is the
  step size for counting up from @('j') to @('jmax'), and the third one is the
  step size for counting up from @('i') to @('imax').  We do not change those
  three occurrences of @('i').</p>

  <p>We submit the proposed generalization as @('lemma1').  The conclusion of
  @('lemma1') is exactly the equality conclusion above except for the
  replacement of those two @('1')s by the new variable @('i0').  The hypothesis
  of @('lemma1') requires all the variables to be naturals.  But the proof
  attempt fails!  The checkpoint is shown below.</p>

  @({
  (defthm lemma1
    (implies
     (and (natp imax)
          (natp jmax)
          (natp i0))
     (equal
      (append$+
       (lambda$ (loop$-gvars loop$-ivars)
                (collect$+ (lambda$ (loop$-gvars loop$-ivars)
                                    (cons (car loop$-gvars)
                                          (car loop$-ivars)))
                           (list (car loop$-ivars))
                           (loop$-as (list (from-to-by 1 (car loop$-gvars) 1)))))
       (list jmax)
       (loop$-as (list (from-to-by i0 imax 1))))
      (all-pairs-helper1 i0 imax jmax))))

  *** Key checkpoint under a top-level induction: ***

  Subgoal *1/6''
  (IMPLIES
   (AND
    (<= I0 IMAX)
    (EQUAL
     (APPEND$+
         (LAMBDA$
              (LOOP$-GVARS LOOP$-IVARS)
              (COLLECT$+ (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS)
                                  (CONS (CAR LOOP$-GVARS)
                                        (CAR LOOP$-IVARS)))
                         (LIST (CAR LOOP$-IVARS))
                         (LOOP$-AS (LIST (FROM-TO-BY 1 (CAR LOOP$-GVARS) 1)))))
         (LIST JMAX)
         (LOOP$-AS (LIST (FROM-TO-BY (+ 1 I0) IMAX 1))))
     (ALL-PAIRS-HELPER1 (+ 1 I0) IMAX JMAX))
    (INTEGERP IMAX)
    (<= 0 IMAX)
    (INTEGERP JMAX)
    (<= 0 JMAX)
    (INTEGERP I0)
    (<= 0 I0))
   (EQUAL (APPEND (COLLECT$+ (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS)
                                      (CONS (CAR LOOP$-GVARS)
                                            (CAR LOOP$-IVARS)))
                             (LIST I0)
                             (LOOP$-AS (LIST (FROM-TO-BY 1 JMAX 1))))
                  (ALL-PAIRS-HELPER1 (+ 1 I0) IMAX JMAX))
          (APPEND (ALL-PAIRS-HELPER2 I0 1 JMAX)
                  (ALL-PAIRS-HELPER1 (+ 1 I0) IMAX JMAX))))
  })

  <p>Notice that we're trying to prove something of the form</p>

  @({
  (EQUAL (APPEND a1 b1)
         (APPEND a2 b2))
  })

  <p>where @('b1') and @('b2') are identical.  So we will prove @('(EQUAL a1
  a2)').</p>

  <p>But again, this is inductive.  The @('(from-to-by 1 jmax 1)') and the
  @('(all-pairs-helper2 i0 1 jmax)') are both counting up from @('1') as the
  initial value of @('j').  We need to generalize those @('1')s to @('j0').
  So we submit the following as @('lemma2').  And it succeeds!</p>

  @({
  (defthm lemma2
    (implies (and (natp imax)
                  (natp jmax)
                  (natp i0)
                  (natp j0))
             (equal (collect$+ (lambda$ (loop$-gvars loop$-ivars)
                                        (cons (car loop$-gvars)
                                              (car loop$-ivars)))
                               (list i0)
                               (loop$-as (list (from-to-by j0 jmax 1))))
                    (all-pairs-helper2 i0 j0 jmax))))
  })

  <p>So now we return to @('lemma1'), whose checkpoint suggested @('lemma2').
  But it fails again, this time with a different checkpoint</p>

  @({
  (defthm lemma1
    (implies
     (and (natp imax)
          (natp jmax)
          (natp i0))
     (equal
      (append$+
       (lambda$ (loop$-gvars loop$-ivars)
                (collect$+ (lambda$ (loop$-gvars loop$-ivars)
                                    (cons (car loop$-gvars)
                                          (car loop$-ivars)))
                           (list (car loop$-ivars))
                           (loop$-as (list (from-to-by 1 (car loop$-gvars) 1)))))
       (list jmax)
       (loop$-as (list (from-to-by i0 imax 1))))
      (all-pairs-helper1 i0 imax jmax))))

  *** Key checkpoint at the top level: ***

  [1]Goal
  (APPLY$-WARRANT-COLLECT$+)
  })

  <p>Note that this checkpoint comes from a forcing round (the clue is the
  &ldquo;@('[1]') prefix to the @('Goal')), which means the proof succeeded except
  for some hypotheses that were forced so that certain lemmas could fire and
  now have to be proved.  But the hypothesis above is the warrant for
  @('collect$+').  We need the warrant for @('collect$+') because that function
  is being applied with @('apply$') every time @('append$+') iterates.  This is
  easy to fix.  We just add the warrant as a hypothesis to @('lemma1').</p>

  @({
  (defthm lemma1
    (IMPLIES
     (AND (warrant collect$+)
          (natp imax)
          (natp jmax)
          (natp i0))
     (equal
      (append$+
       (lambda$ (loop$-gvars loop$-ivars)
                (collect$+ (lambda$ (loop$-gvars loop$-ivars)
                                    (cons (car loop$-gvars)
                                          (car loop$-ivars)))
                           (list (car loop$-ivars))
                           (loop$-as (list (from-to-by 1 (car loop$-gvars) 1)))))
       (list jmax)
       (loop$-as (list (from-to-by i0 imax 1))))
      (all-pairs-helper1 i0 imax jmax))))
  })

  <p>This proof succeeds.</p>

  <p>So now we return to @('main').  By the way, because we expect the theorem
  to be proved by applying @('lemma1'), we provide the hint that tells the
  prover not to even try induction.  This just reduces the output if the proof
  fails.</p>

  <p>Unfortunately this attempt fails, but with two easy-to-fix
  checkpoints.</p>

  @({
  (defthm main
    (implies (and (natp imax)
                  (natp jmax))
             (equal (all-pairs-loop$ imax jmax)
                    (all-pairs imax jmax)))
    :hints (("Goal" :do-not-induct t)))

  *** Key checkpoints at the top level: ***

  [1]Subgoal 2
  (APPLY$-WARRANT-MAKE-PAIR)

  [1]Subgoal 1
  (APPLY$-WARRANT-COLLECT$+)
  })

  <p>Note that the checkpoints are forcing round subgoals showing that we need
  two warrants.  So we add both warrants to @('main')'s hypotheses.  And we're
  done.</p>

  @({
  (defthm main
    (implies (and (warrant collect$+ make-pair)
                  (natp imax)
                  (natp jmax))
             (equal (all-pairs-loop$ imax jmax)
                    (all-pairs imax jmax)))
    :hints (("Goal" :do-not-induct t)))
  })

  <p>Note: The @(':do-not-induct') hint could be deleted because the theorem is
  proved without appealing to induction anyway.</p>

  <p>You might wonder why we need the warrant on @('make-pairs').  It never arose in any
  checkpoint except in the very last failed proof.</p>

  <p>The first time we tried to prove @('main') we failed, and got this checkpoint.</p>

  @({
  Goal''
  (IMPLIES
   (AND (INTEGERP IMAX)
        (<= 0 IMAX)
        (INTEGERP JMAX)
        (<= 0 JMAX))
   (EQUAL
    (APPEND$+
     (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS)
              (COLLECT$+ (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS)
                                  (CONS (CAR LOOP$-GVARS)
                                        (CAR LOOP$-IVARS)))
                         (LIST (CAR LOOP$-IVARS))
                         (LOOP$-AS (LIST (FROM-TO-BY 1 (CAR LOOP$-GVARS) 1)))))
     (LIST JMAX)
     (LOOP$-AS (LIST (FROM-TO-BY 1 IMAX 1))))
    (ALL-PAIRS-HELPER1 1 IMAX JMAX)))
  })

  <p>The innermost @('lambda$') is the body of the innermost @('loop$')
  statement, @('(loop$ for j from 1 to jmax collect (make-pair i j))'), except
  it has been simplified by the expansion of @('(make-pair i j)') to @('(cons i
  j)').  That expansion of @('make-pair') inside a @('lambda$') required the
  warrant for @('make-pair') and that was forced to produce the @('cons').</p>

  <p>Had that first proof attempt at @('main') succeeded except for that forced
  subgoal, a forcing round would have brought to our attention the need for the
  warrant on @('make-pair').  But that proof attempt failed because the prover could not
  do a suitable induction to prove @('Goal''').  Indeed, that is what led us to @('lemma1').</p>

  <p>But forced subgoals are not reported if the proof fails for other reasons.
  So we were left unaware that we were depending on the warrant for
  @('make-pair').  In the penultimate failed proof @('main') just above, the
  same forced expansion of @('make-pair') occurred and this time the proof
  succeeded except for the forced subgoals requiring warrants for
  @('make-pair') and @('collect$+').  That finally brought the @('make-pair')
  expansion to our attention.</p>

  <p>The more experienced ACL2 user would have noticed (indeed, did notice!)
  the expansion of @('make-pair') in @('Goal''') above and understood the
  warrant for @('make-pair') was needed but wanted to see what would happen if
  that fact was overlooked.</p>

  <p>The final series of events to solve this problem is shown below.</p>

  @({
  ; Include standard apply$ book.
  (include-book "projects/apply/top" :dir :system)

  ; Define and verify the guards of the recursive all-pairs.
  (defun make-pair (i j)
    (declare (xargs :guard t))
    (cons i j))

  (defun all-pairs-helper2 (i j jmax)
    (declare (xargs :measure (nfix (- (+ (nfix jmax) 1) (nfix j)))
                    :guard (and (natp i) (natp j) (natp jmax))))
    (let ((j (nfix j))
          (jmax (nfix jmax)))
      (cond
       ((> j jmax) nil)
       (t (cons (make-pair i j)
                (all-pairs-helper2 i (+ 1 j) jmax))))))

  (defun all-pairs-helper1 (i imax jmax)
    (declare (xargs :measure (nfix (- (+ (nfix imax) 1) (nfix i)))
                    :guard (and (natp i) (natp imax) (natp jmax))))
    (let ((i (nfix i))
          (imax (nfix imax)))
      (cond
       ((> i imax) nil)
       (t (append (all-pairs-helper2 i 1 jmax)
                  (all-pairs-helper1 (+ 1 i) imax jmax))))))

  (defun all-pairs (imax jmax)
    (declare (xargs :guard (and (natp imax) (natp jmax))))
    (all-pairs-helper1 1 imax jmax))

  ; Warrant make-pair so we can use it in a loop$.
  (defwarrant make-pair)

  ; Define and verify the guards of the loop$ version.
  (defun all-pairs-loop$ (imax jmax)
    (declare (xargs :guard (and (natp imax) (natp jmax))))
    (loop$ for i from 1 to imax
           append
           :guard (natp jmax)
           (loop$ for j from 1 to jmax
                  collect (make-pair i j))))

  ; Prove that the generalized inner loop$ is all-pairs-helper2.
  (defthm lemma2
    (implies (and (natp imax)
                  (natp jmax)
                  (natp i0)
                  (natp j0))
             (equal (collect$+ (lambda$ (loop$-gvars loop$-ivars)
                                        (cons (car loop$-gvars)
                                              (car loop$-ivars)))
                               (list i0)
                               (loop$-as (list (from-to-by j0 jmax 1))))
                    (all-pairs-helper2 i0 j0 jmax))))

  ; Prove that the generalized outer loop$ is all-pairs-helper1.
  (defthm lemma1
    (implies
     (and (warrant collect$+)
          (natp imax)
          (natp jmax)
          (natp i0))
     (equal
      (append$+
       (lambda$ (loop$-gvars loop$-ivars)
                (collect$+ (lambda$ (loop$-gvars loop$-ivars)
                                    (cons (car loop$-gvars)
                                          (car loop$-ivars)))
                           (list (car loop$-ivars))
                           (loop$-as (list (from-to-by 1 (car loop$-gvars) 1)))))
       (list jmax)
       (loop$-as (list (from-to-by i0 imax 1))))
      (all-pairs-helper1 i0 imax jmax))))

  ; Main theorem
  (defthm main
    (implies (and (warrant collect$+ make-pair)
                  (natp imax)
                  (natp jmax))
             (equal (all-pairs-loop$ imax jmax)
                    (all-pairs imax jmax))))
  })

  <p>Now go to @(see lp-section-12) (or return to the <see topic='@(url
  lp-section-0)'>Table of Contents</see>).</p>")

(defxdoc lp-section-12
  :parents (loop$-primer)
  :short "Challenge Proof Problems about @('FOR') @('Loop$')s"
  :long "<h3>LP12: Challenge Proof Problems about @('FOR') @('Loop$')s</h3>

  <p>If you have not already, warm up by proving the correctness of your
  solutions to the problems in @(see lp-section-8).</p>

  <p>Remember to operate in a session in which you have included the
  standard @('loop$') book.</p>

  @({
  (include-book "projects/apply/top" :dir :system)
  })

  <p>Our answers to the problems in @(see lp-section-8) are in @(see
  community-books) file @('demos/loop-primer/lp8.lisp'), and our answers to the
  problems below are in @(see community-books) file
  @('demos/loop-primer/lp12.lisp').</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP12-1</b> Define @('(assoc-equal-loop$ x alist)') to be equal to
  @('(assoc-equal x alist)') when @('(alistp alist)').  Verify the guards of
  @('assoc-equal-loop$') and prove that your function satisfies the
  specification above.  Is your function in fact unconditionally equal to
  @('assoc-equal')?  If so, prove it; if not, show a counterexample.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP12-2</b> Under what conditions is the following a theorem?  Fill in
  the blank and prove the theorem.</p>

  @({
  (defthm LP12-2
    (implies ...
             (equal (loop$ for x in keys as y in vals collect (cons x y))
                    (pairlis$ keys vals)))
    :rule-classes nil)
  })

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP12-3</b> Prove</p>

  @({
  (defthm LP12-3
    (equal (* 2 (len (loop$ for tl on lst append tl)))
           (* (len lst) (+ (len lst) 1))))
  })

  <p><i>Hint:</i> By phrasing the challenge with the multiplication by 2 on the
  left-hand side, we produce a conjecture that can be proved (perhaps with a
  few lemmas) without the need for &ldquo;heavy duty&rdquo; arithmetic books.  Had we
  divided by 2 on the right-hand side, we'd have brought division into the
  problem which we intentionally avoided.  You will still need a lemma or two,
  discoverable by The Method.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP12-4</b>  Define</p>

  @({
  (defun nats (n)
    (cond ((zp n) (list 0))
          (t (append (nats (- n 1)) (list n)))))
  })

  <p>and prove that the obvious @('loop$') statement is equivalent to @('(nats
  n)') when @('n') is a natural.  Make your @('defthm') have @(':rule-classes
  nil') so as not to interfere with your work on the next problem.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP12-5</b> Define</p>

  @({
  (defun nats-up (i n)
    (declare (xargs :measure (nfix (- (+ (nfix n) 1) (nfix i)))))
    (let ((i (nfix i))
          (n (nfix n)))
      (cond ((> i n) nil)
            (t (cons i (nats-up (+ i 1) n))))))
  })

  <p>Prove</p>

  @({
  (defthm LP12-5
    (implies (natp n)
             (equal (loop$ for i from 0 to n collect i)
                    (nats-up 0 n)))
    :rule-classes nil)
  })

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP12-6</b> Fill in the blanks below and prove the theorem.  You may
  need hints.  If not, just delete the :hints setting.</p>

  @({
  (defthm LP12-6
    (implies (true-listp lst)
             (equal (loop$ ...)
                    (strip-cars lst)))
    :hints ...
    :rule-classes nil)
  })

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP12-7</b> Prove the following, adding hints if necessary.  Otherwise,
  just delete the @(':hints') setting.</p>

  @({
  (defthm LP12-7
    (loop$ for pair in (loop$ for key in keys
                              as  val from 0 to (+ (len keys) -1)
                              collect (cons key val))
           always (integerp (cdr pair)))
    :hints ...)
  })

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP12-8</b>  Fill in the blanks below and then prove the theorem.  You may
  need hints.  If not, just delete the @(':hints') setting.</p>

  @({
  (defthm LP12-8
    (implies (natp n)
             (equal (loop$ ...)
                    (nth n lst)))
    :hints ...
    :rule-classes nil)
  })

  <p>Now go to @(see lp-section-13) (or return to the <see topic='@(url
  lp-section-0)'>Table of Contents</see>).</p>")

(defxdoc lp-section-13
  :parents (loop$-primer)
  :short "Examples of @('DO') @('Loop$')s"
  :long "<h3>LP13: Examples of @('DO') @('Loop$')s</h3>

  <p>Below is a log of an ACL2 session demonstrating the behavior of a few
  @('DO') @('loop$')s.  As usual with @('loop$')s, one should always work in a
  session in which the book shown below is included.  The examples below do not
  illustrate guards or proofs about @('DO') @('loop$')s.</p>

  <p>We'll describe the syntax and semantics of @('DO') @('loop$')s later.  But
  we expect you can intuit the syntax and semantics of these @('loop$')
  statements from these examples.  The following may help if you're
  unfamiliar with the following Common Lisp primitives.</p>

  <p>In ACL2, <b>These primitives may only be used within @('DO') @('loop$')s!</b></p>

  <ul>

  <li>@('(RETURN ')<i>expr</i>@(')') terminates the @('loop$') and returns
  the value of <i>expr</i> as the value.</li>

  <li>@('(SETQ ')<i>var&nbsp;expr</i>@(')') evaluates <i>expr</i> and assigns the
  value to the variable <i>var</i>.  Parallel assignment with @('mv-setq') is also
  supported but not illustrated here.</li>

  <li>@('(PROGN ')<i>stmt_1 &hellip; stmt_n</i>@(')') evaluates each
  <i>stmt_i</i> in turn and returns the value of the last one.</li>

  <li>@('(LOOP-FINISH)') terminates the iteration in the @('loop$') and passes
  control to the @('FINALLY') clause, if any.</li>

  </ul>

  <p>We start the session with the following commands, whose output we do not
  display here.  Note that we use @(tsee defstobj) to introduce a
  single-threaded object, @('st'), with one field, @('fld1').  We initialize
  @('(fld1 st)') to 0. In addition, we warrant two of the functions introduced
  by the @(tsee defstobj).  We warrant those functions because they are
  user-defined @(':logic') mode functions that we'll use in a @('DO')
  @('loop$').  @('Defstobj') does not automatically badge or warrant the
  functions it defines but they are warrantable.</p>

  @({
  (include-book "projects/apply/top" :dir :system)
  (defstobj st fld1)
  (update-fld1 0 st)
  (defwarrant fld1)
  (defwarrant update-fld1)
  })

  <p>So having set up our session, we now experiment with @('DO')
  @('loop$')s.</p>

  @({

  ; Reverse the elements of the initial value of temp.

  ACL2 !>(loop$ with temp = '(a b c)
                with  ans = nil
                do
                (cond ((endp temp) (return ans))
                      (t (progn (setq ans (cons (car temp) ans))
                                (setq temp (cdr temp))))))
  (C B A)

  ; Reverse the elements of lst down to the first xxx, or return
  ; not-found if there is no xxx in lst.

  ACL2 !>(defun reverse-to-xxx (lst)
           (loop$ with temp = lst
                  with  ans = nil
                  do
                  (cond ((endp temp) (return 'not-found))
                        (t (progn (cond ((eq (car temp) 'xxx) (loop-finish))
                                        (t (setq ans (cons (car temp) ans))))
                                  (setq temp (cdr temp)))))
                  finally
                  (return ans)))

  Since REVERSE-TO-XXX is non-recursive, its admission is trivial.  We
  could deduce no constraints on the type of REVERSE-TO-XXX.

  Summary
  Form:  ( DEFUN REVERSE-TO-XXX ...)
  Rules: NIL
  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
   REVERSE-TO-XXX

  ACL2 !>(reverse-to-xxx '(a b c xxx d e f))
  (C B A)

  ACL2 !>(reverse-to-xxx '(a b c d e f))
  NOT-FOUND

  ; In the next example we will reverse the elements of the initial value of
  ; temp, except for the xxx's which we just drop but count.  We use (fld1 st)
  ; to store the accumulated count.  This loop$ returns the reversed elements
  ; and the final value of st.  But first we'll show that (fld1 st) is
  ; initially 0.

  ACL2 !>(fld1 st)
  0

  ACL2 !>(loop$ with temp = '(a b c xxx d e xxx f g)
                with ans = nil
                do
                :values (nil st)
                (cond ((endp temp) (return (mv ans st)))
                      (t (progn
                           (cond ((eq (car temp) 'xxx)
                                  (setq st (update-fld1 (+ 1 (fld1 st)) st)))
                                 (t (setq ans (cons (car temp) ans))))
                           (setq temp (cdr temp))))))
  ((G F E D C B A) <st>)

  ACL2 !>(fld1 st)
  2
  })

  <p>We included the last example showing that stobjs can be used inside of
  @('DO') @('loop$')s just to alert you to that feature.  However, in the rest
  of this primer we do not deal with stobjs in @('loop$') because there is
  enough to cover without that!</p>

  <p>See the ACL2 documentation topic @(see DO-loop$) for a more thorough
  discussion of @('DO') @('loop$')s.</p>

  <p>Now go to @(see lp-section-14) (or return to the <see topic='@(url
  lp-section-0)'>Table of Contents</see>).</p>")

(defxdoc lp-section-14
  :parents (loop$-primer)
  :short "Challenge Problems about @('DO') @('Loop$')s"
  :long "<h3>LP14: Challenge Problems about @('DO') @('Loop$')s</h3>

  <p>In this section you'll be asked to write and evaluate some @('DO')
  @('loop$')s based entirely on the examples given in the previous section.
  We'll deal with termination, guards, proofs, etc., later.</p>

  <p>We want all iteration in your answers to be done with @('DO') @('loop$')s
  even if the problem could be solved with a @('FOR') @('loop$').</p>

  <p>Our answers to the problems in this section are in @(see community-books)
  file @('demos/loop-primer/lp14.lisp').</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP14-1:</b> Make a list of the integers from 10 down to 0.</p>

  <p><b>Expected Value:</b>@('(10 9 8 7 6 5 4 3 2 1 0)')</p>

  <p>Ok, we know this is a silly question if taken literally!  Why use
  iteration at all if the answer is a constant?  If you want to cheat,
  just enter</p>

  @({
  (loop$ with ans = '(10 9 8 7 6 5 4 3 2 1 0) do (return ans))
  })

  <p>But the spirit of these questions is to use iteration and, if it helps,
  imagine we'd asked you to write a @('loop$') that returns the list of
  integers from 1000000 down to 0!</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP14-2:</b> Sum the naturals less than or equal to 100.</p>

  <p><b>Expected Value:</b> @('5050')</p>

  <p>Hint: Write the @('loop$') so that it counts down!  If you count up you'll
  have to provide a measure term, which can be done by including @(':measure')
  <i>measure-term</i> immediately after the @('DO') operand and before the
  body.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP14-3:</b> Sum the squares of the naturals less than or equal to 100,
  using the following function to square.</p>

  @({
  (defun sq (x) (* x x))
  })

  <p><b>Expected Value:</b> @('338350')</p>


  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP14-4:</b> Write a @('DO') that finds the first occurrence of the
  symbol @('XXX') in the list @(''(A B C XXX D E F)') and returns the tail of
  the list starting with that occurrence.</p>

  <p><b>Expected Value:</b> @('(XXX D E F)')</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP14-5:</b> Fill in the blank below so that the next form is a theorem.
  You do not have to prove the theorem (but it shouldn't be hard).</p>

  @({
  (defun do-loop$-member (e lst)
    (loop$ ...))

  (defthm lp14-5
    (equal (do-loop$-member e lst)
           (member e lst))
    :rule-classes nil)
  })

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP14-6:</b> Given the following</p>

  @({
  (defun steps-for-member (e lst steps)
    (cond ((endp lst) (list steps nil))
          ((equal (car lst) e) (list steps lst))
          (t (steps-for-member e (cdr lst) (+ 1 steps)))))
  })

  <p>fill in the blank so that this is a theorem.</p>

  @({
  (defthm lp14-6
    (equal (loop$ ...)
           (steps-for-member e lst steps))
    :rule-classes nil)
  })

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP14-7:</b>Write a @('DO') to compute the list of all pairs @('(i
  . j)') such that 1 &le; @('i') &le; 3 and 1 &le; @('j') &le; 4.</p>

  <p><b>Expected Value:</b></p>

  @({
  ((1 . 1)
   (1 . 2)
   (1 . 3)
   (1 . 4)
   (2 . 1)
   (2 . 2)
   (2 . 3)
   (2 . 4)
   (3 . 1)
   (3 . 2)
   (3 . 3)
   (3 . 4))
  })

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>Now go to @(see lp-section-15) (or return to the <see topic='@(url
  lp-section-0)'>Table of Contents</see>).</p>")

(defxdoc lp-section-15
  :parents (loop$-primer)
  :short "Informal Syntax and Semantics of @('DO') @('Loop$')s"
  :long "<h3>LP15: Informal Syntax and Semantics of @('DO') @('Loop$')s</h3>

  <p>The &ldquo;most elaborate&rdquo; @('DO') @('loop$') looks like this.</p>

  @({
  (LOOP$ WITH var1 OF-TYPE spec1 = init1 ; a WITH declaration
         WITH var2 OF-TYPE spec2 = init2
         ...
         DO
         :measure m
         :guard do-guard
         :values v
         do-body
         FINALLY
         :guard fin-guard
         fin-body)
   })

  <p>where much of that is optional: &ldquo;@('OF-TYPE speci')&rdquo;,
  &ldquo;@('= initi')&rdquo; (when &ldquo;@('OF-TYPE speci')&rdquo; is
  present), &ldquo;@(':MEASURE m')&rdquo;, the two &ldquo;@(':GUARD')
  ...&rdquo; clauses, &ldquo;@(':VALUES v')&rdquo;, and &ldquo;@('FINALLY
  fin-body')&rdquo;.  If the @(':MEASURE') is omitted, ACL2 tries to guess a
  likely measure using the same heuristic it does with recursive @(tsee
  defun)s.  If @(':VALUES') is omitted then @('v') defaults to @('(nil)').</p>

  <p>All ACL2 function symbols in @('m'), @('do-body'), and @('fin-body') must
  be @(see badge)d so @(tsee apply$) can handle them.  Furthermore, they must
  be @(see warrant)ed if proofs are to be done about them or if they are in
  @(see logic) mode and are called during evaluation.</p>

  <p>As you've already inferred from our examples, @('do-body') and
  @('fin-body') are not normal ACL2 terms!  They allow restricted uses of
  @('RETURN'), @('PROGN'), @('SETQ'), @('MV-SETQ'), and @('LOOP-FINISH').</p>

  <p>As for semantics, every legal @('DO') @('loop$') translates into a term
  of the form</p>

  @({
  (DO$ m-lambda
       alist
       do-body-lambda
       fin-body-lambda
       a5
       a6)
  })

  <p>where @('m-lambda'), @('do-body-lambda'), and @('fin-body-lambda') are
  quoted @('LAMBDA') objects derived from the respective terms in the
  @('loop$') statement.  @('Alist') is an association list that maps the
  variables of those terms to their initial values.  We discuss the other three
  arguments later.</p>

  <p>All three of these @('LAMBDA') objects operate on @('alist').  The
  @('m-lambda') may return a natural, and otherwise must return a list of naturals which is treated as a
  lexicographic tuple whose first component is the most significant.  The other
  two @('LAMBDA') objects return a triple of the form @('(exit-token value
  new-alist)').  The @('exit-token') is @(':RETURN'), @(':LOOP-FINISH'), or
  @('NIL'), and indicates what happens next: the @('value') is to be returned
  as the value of the @('loop$'), the @('fin-body-lambda') is to be applied to
  the @('new-alist'), or the @('loop$') is to iterate again on @('new-alist').
  But before the iteration, the @('m-lambda') is applied to the @('new-alist')
  and must be of smaller measure according to @(tsee L<) for iteration to
  continue.</p>

  <p>If the given measure fails to decrease, then, logically speaking, @('a5')
  is used to compute a default answer.  (That argument is actually the output
  signature of the @('loop$') specifying how many values are to be returned and
  whether each value is an ordinary object, a double-float, or a @(see stobj).)
  However, in execution, an error is signaled if the measure fails to decrease.
  Such runtime errors (including @('OF-TYPE') and guard violations if guards
  are being checked) are reported using @('a6') which is just a
  quoted constant about the original @('loop$') statement.  (In fact, @('a6')
  is logically irrelevant and the theorem prover replaces quoted non-@('nil')
  final argument to @('do$') by @('nil') in proofs as part of the cleaning-up
  process.)</p>

  <p>Consider this simple @('DO') @('loop$') and its cleaned-up semantics as
  shown by the @(':')@(tsee tcp) command.  (We have re-pretty-printed it
  to add comments and highlight some symmetries.)</p>

  @({
  ACL2 !>:tcp (loop$ with i = n
                     with ans = 0
                     do
                     (if (zp i)
                         (return ans)
                         (progn (setq ans (+ 1 ans))
                                (setq i (- i 1)))))
   (DO$
;    measure lambda:
     (LAMBDA$ (ALIST)
       (ACL2-COUNT (CDR (ASSOC-EQ-SAFE 'I ALIST))))

;    initial alist:
     (LIST (CONS 'I N)
           (CONS 'ANS 0))

;    do-body lambda:
     (LAMBDA$ (ALIST)
       (IF (ZP (CDR (ASSOC-EQ-SAFE 'I ALIST)))
           (LIST :RETURN
                 (CDR (ASSOC-EQ-SAFE 'ANS ALIST))
                 (LIST (CONS 'I (CDR (ASSOC-EQ-SAFE 'I ALIST)))
                       (CONS 'ANS (CDR (ASSOC-EQ-SAFE 'ANS ALIST)))))
           (LIST NIL
                 NIL
                 (LIST (CONS 'I (+ -1 (CDR (ASSOC-EQ-SAFE 'I ALIST))))
                       (CONS 'ANS (+ 1 (CDR (ASSOC-EQ-SAFE 'ANS ALIST))))))))

;    fin-body lambda (irrelevant here)
     (LAMBDA$ (ALIST)
       (LIST NIL
             NIL
             (LIST (CONS 'I (CDR (ASSOC-EQ-SAFE 'I ALIST)))
                   (CONS 'ANS (CDR (ASSOC-EQ-SAFE 'ANS ALIST))))))

;    irrelevant args a5 and a6
     '(NIL) NIL)
  })

  <p>@('ASSOC-EQ-SAFE') is just @('ASSOC-EQ') with a slightly weaker guard.
  Think of @('(CDR (ASSOC-EQ-SAFE 'var ALIST))') as the current value of the
  local variable @('var').  The measure is that the @('ACL2-COUNT') of the
  current value of @('I') decreases.  The output of the @('do-body')
  @('lambda') is a triple.  The true branch of the @('IF') indicate iteration
  is to stop and return the current value of @('ANS').  The false branch
  indicates iteration is to continue with the new alist given as the third
  element of the triple.  The @('fin-body') @('lambda') is irrelevant because
  there is no @(':LOOP-FINISH') exit in the do-body.</p>

  <p>Of course, the semantics of @('do$') is explicit in its definition.
  So you might want to execute @(':pe do$') in your ACL2 session and just
  read how @('do$') operates.</p>

  <p>We realize the above descriptions are pretty sketchy.  But in the coming
  discussions and proof problems we'll limit ourselves to @('DO') @('loop$')s
  without @('of-type')s or @('guards'), they'll all return single non-@(tsee
  stobj) values so the @(':values') option won't be needed, and you won't really
  need to use the @('finally') clause or any fancier bodies than we show in our
  examples.</p>

  <p>For more details about both the syntax and semantics of @('DO')
  @('loop$')s see @(see do-loop$).  <b>But beware!  That link takes you out of
  the @('loop$') primer!</b> To get back here either use your browser's
  &ldquo;back&rdquo; button or remember to return to @('lp-section-15')!</p>

  <p>Now go to @(see lp-section-16) (or return to the <see topic='@(url
  lp-section-0)'>Table of Contents</see>).</p>")

(defxdoc lp-section-16
  :parents (loop$-primer)
  :short "Proving Theorems about @('DO') @('Loop$')s"
  :long "<h3>LP16: Proving Theorems about @('DO') @('Loop$')s</h3>

  <p>Let's prove a theorem about a @('DO') @('loop$').  Specifically, let's
  prove</p>

  @({
  (defthm main
    (implies (natp n)
             (equal (loop$ with i = n
                           with ans = 0
                           do
                           (if (zp i)
                               (return ans)
                               (progn (setq ans (+ 1 ans))
                                      (setq i (- i 1)))))
                    n)))
  })

  <p>A few words of warning are appropriate.</p>

  <ul>

  <li>The Method (see @(see the-method)) is a good way to proceed:  try to
  prove the theorem expecting it to fail and look at the checkpoints.</li>

  <li>Unsurprisingly, the theorem above has to be <i>generalized</i> before it
  can be proved.  But it can feel strange to generalize a @('loop$').</li>

  <li>If we prove a lemma that rewrites a @('loop$') expression we have to
  remember that before rewrite rules are applied the interior terms are
  rewritten.  In particular, ACL2 can rewrite the bodies of the @('lambda')
  objects.  The most common changes are that non-recursive functions are
  generally expanded (depending on the theory in use) and @('IF')s
  are normalized.  That means we need to normalize the bodies of any @('loop$')
  we use in a lemma if we expect that lemma to match a term being rewritten!
  This observation is relevant here because @(tsee zp) is non-recursively
  defined and so will expand when the body of the @('loop$') above is
  rewritten.</li>

  <li>ACL2 does not display @('do$') terms as @('DO') @('loop$')s.  So get
  used to reading @('do$') terms and thinking of @('loop$') statements!
  (We may fix this someday but at the moment we find it advantageous to really
  see the terms the prover is dealing with!)</li>

  </ul>

  <p><b>A Tedious Recipe for Proving Theorems about @('DO') @('Loop$')s</b></p>

  <p>When you first start proving theorems about @('DO') @('loop$')s it might
  be helpful to follow the tedious recipe below.  It will familiarize you with
  the semantics of @('DO') @('loop$')s and teach you certain techniques that
  are easy applications of lessons you've already internalized as an
  experienced ACL2 user, albeit one unfamiliar with @('loop$').  But after a
  little experience you'll find it straightforward to skip some steps!</p>

  <ul>
  <li>Use The Method to find the normal form of the @('loop$').</li>

  <li>Define a recursive function that computes the value of the @('loop$')
  using the same algorithm as the @('loop$'). This function can serve two
  purposes.  First, it can be an intermediate stop on the way to proving that
  the @('loop$') satisfies your specification.  We'll make this clear in the
  next point.  Second, it can suggest an induction scheme that is probably
  useful.  We'll return to this point at the end of our recipe for proving
  things about @('DO') @('loop$')s.</li>

  <li>Prove that the @('loop$') computes the same value as the function.  We
  frequently refer to this as &ldquo;lemma 1&rdquo; in the recipe.  Generally
  you will have to generalize the @('loop$') to prove it by the induction
  suggested by the function.  And you will have to write the normal form of the
  @('loop$') body instead of the &ldquo;pretty&rdquo; form used in the main
  theorem so this lemma can be used to hit the rewritten @('loop$') in the
  proof of the main theorem later.</li>

  <li>Prove that the function satisfies the specification.  We
  frequently refer to this as &ldquo;lemma 2&rdquo;.</li>

  <li>Prove that the @('loop$') satisfies the specification by chaining
  together the two lemmas.</li>

  </ul>

  <p>Of course, as with all &ldquo;recipes&rdquo;, sometimes you have to adjust
  depending on the ingredients at hand.  Sometimes you can just write the body of
  the @('loop$') in normal form to begin with.   Sometimes you do not have to define a
  special function because the @('loop$') itself or a function already in the
  conjecture suggests an appropriate induction.  Sometimes you may find it
  easier to copy the @('do$') form revealed by The Method into your statement
  of lemma 1 and generalize that form, rather than try to express lemma 1 as a
  @('loop$').  You may also be content to skip the &ldquo;intermediate
  stop&rdquo; of lemma 1 altogether and prove that the @('loop$') satisfies a
  generalized specification, sometimes providing an @(':induct') hint instead
  of inserting the special function into the lemma.  Sometimes you do not have
  to generalize.  Sometimes instead of proving lemma 1 and lemma 2 you can just
  prove the main goal directly.  As an experienced ACL2 user you will recognize
  when you can skip steps in this recipe.  We spell the recipe out rigidly here
  just to give you one promising way to proceed.</p>

  <p>We're going to prove the theorem</p>

  @({
  (defthm main
    (implies (natp n)
             (equal (loop$ with i = n
                           with ans = 0
                           do
                           (if (zp i)
                               (return ans)
                               (progn (setq ans (+ 1 ans))
                                      (setq i (- i 1)))))
                    n)))
  })

  <p>both ways, first by following the tedious recipe, and then the way a user
  familiar with @('DO') @('loop$') proofs might do it.</p>

  <p>So here goes!  Following the recipe to prove @('main') above, we first try
  The Method.  The prover tries an induction suggested by the @('DO')
  @('loop$'), namely induction on @('N') by @('-1'), but without instantiating
  @('ANS') because the initial value of @('ANS') is the constant @('0').  We
  know this proof will fail and it does.  The pre-induction checkpoint is shown
  below.</p>

  @({
  *** Key checkpoint at the top level: ***

  Goal''
  (IMPLIES
   (AND (INTEGERP N) (<= 0 N))
   (EQUAL
    (DO$
       (LAMBDA$ (ALIST)
                (ACL2-COUNT (CDR (ASSOC-EQ-SAFE 'I ALIST))))
       (CONS (CONS 'I N) '((ANS . 0)))
       (LAMBDA$
            (ALIST)
            (IF (INTEGERP (CDR (ASSOC-EQ-SAFE 'I ALIST)))
                (IF (< 0 (CDR (ASSOC-EQ-SAFE 'I ALIST)))
                    (LIST NIL NIL
                          (LIST (CONS 'I
                                      (+ -1 (CDR (ASSOC-EQ-SAFE 'I ALIST))))
                                (CONS 'ANS
                                      (+ 1 (CDR (ASSOC-EQ-SAFE 'ANS ALIST))))))
                    (LIST :RETURN (CDR (ASSOC-EQ-SAFE 'ANS ALIST))
                          (LIST (CONS 'I (CDR (ASSOC-EQ-SAFE 'I ALIST)))
                                (CONS 'ANS
                                      (CDR (ASSOC-EQ-SAFE 'ANS ALIST))))))
                (LIST :RETURN (CDR (ASSOC-EQ-SAFE 'ANS ALIST))
                      (LIST (CONS 'I (CDR (ASSOC-EQ-SAFE 'I ALIST)))
                            (CONS 'ANS
                                  (CDR (ASSOC-EQ-SAFE 'ANS ALIST)))))))
       (LAMBDA$ (ALIST)
                (LIST NIL NIL
                      (LIST (CONS 'I (CDR (ASSOC-EQ-SAFE 'I ALIST)))
                            (CONS 'ANS
                                  (CDR (ASSOC-EQ-SAFE 'ANS ALIST))))))
       '(NIL) NIL)
    N))
  })

  <p>Look carefully at the @('do-body') @('lambda'), the second @('lambda')
  object in the @('do$').  The @('(ZP I)') in our original @('DO') @('loop$')
  has opened up, introducing @('(INTEGERP i)') and @('(< 0 i)') and @('IF')
  normalization -- except instead of seeing the simple variable @('I') we see
  its current value in the @('ALIST') being computed on each iteration.</p>

  <p><b>This is valuable information! It tells us what the rewritten body of
  the @('loop$') looks like in the theory in which our proof is being
  conducted.  If we prove a @(':rewrite') rule expecting it to fire during the
  proof of our @('main') theorem, its body must match that shown above!</b></p>

  <p>Now we define the recursive function that is supposed to be operationally
  equivalent to the @('loop$').  This will suggest the induction.</p>

  @({
  (defun copy-nat-ac (i ans)
    (if (zp i)
        ans
        (copy-nat-ac (- i 1)
                     (+ 1 ans))))
  })

  <p>Next comes the hard part.  We state the lemma that equates the @('loop$')
  to the function, but we have to generalize it so it can be proved by induction
  and we have to use the normal form of the body.  We could state the lemma
  in terms of @('DO$') of course, but with a little practice you can usually
  &ldquo;reverse engineer&rdquo; the desired lemma into a @('loop$').  So here
  is the so-called &ldquo;lemma 1&rdquo;.</p>

  @({
  (defthm lemma1
    (implies (and (natp n)
                  (natp ans0))
             (equal (loop$ with i = n
                           with ans = ans0
                           do
                           (if (integerp i)
                               (if (< 0 i)
                                   (progn (setq ans (+ 1 ans))
                                          (setq i (- i 1)))
                                   (return ans))
                               (return ans)))
                    (copy-nat-ac n ans0))))
  })

  <p>Note that we generalized the initial value of @('ans') in the @('loop$')
  from @('0') to @('ans0') and used @('ans0') as the accumulator in
  @('(copy-nat-ac n ans0)').</p>

  <p>By the way, we could have written @('lemma1') in terms of the @('DO$')
  term shown in the checkpoint, rather than as a @('loop$').  But we have to
  generalize that @('0') whether we use a @('loop$') or the @('DO$') term.
  The generalized @('DO$') form of @('lemma1') is</p>

  @({
  (defthm lemma1
    (implies
     (and (natp n)
          (natp ans0))
     (equal
      (DO$
       (LAMBDA$ (ALIST)
                (ACL2-COUNT (CDR (ASSOC-EQ-SAFE 'I ALIST))))
       (CONS (CONS 'I N)
             (cons (cons 'ans ans0)
                   nil)) ; note generalization of 0!
       (LAMBDA$
        (ALIST)
        (IF (INTEGERP (CDR (ASSOC-EQ-SAFE 'I ALIST)))
            (IF (< 0 (CDR (ASSOC-EQ-SAFE 'I ALIST)))
                (LIST NIL NIL
                      (LIST (CONS 'I
                                  (+ -1 (CDR (ASSOC-EQ-SAFE 'I ALIST))))
                            (CONS 'ANS
                                  (+ 1 (CDR (ASSOC-EQ-SAFE 'ANS ALIST))))))
                (LIST :RETURN (CDR (ASSOC-EQ-SAFE 'ANS ALIST))
                      (LIST (CONS 'I (CDR (ASSOC-EQ-SAFE 'I ALIST)))
                            (CONS 'ANS
                                  (CDR (ASSOC-EQ-SAFE 'ANS ALIST))))))
            (LIST :RETURN (CDR (ASSOC-EQ-SAFE 'ANS ALIST))
                  (LIST (CONS 'I (CDR (ASSOC-EQ-SAFE 'I ALIST)))
                        (CONS 'ANS
                              (CDR (ASSOC-EQ-SAFE 'ANS ALIST)))))))
       (LAMBDA$ (ALIST)
                (LIST NIL NIL
                      (LIST (CONS 'I (CDR (ASSOC-EQ-SAFE 'I ALIST)))
                            (CONS 'ANS
                                  (CDR (ASSOC-EQ-SAFE 'ANS ALIST))))))
       '(NIL) NIL)
      (copy-nat-ac n ans0)))).
  })

  <p>The UPPERCASE part above was just copied from the checkpoint and then the
  pair in the initial alist binding @('ANS'), which was @(''(ANS . 0)'), was
  replaced by @('(cons (cons 'ans ans0) nil)').  So while it looks messy, it's
  not hard to enter.  Furthermore, it saves us from having to figure out the
  normal form &mdash; it's already in the checkpoint.  The @('DO$') term in
  this version of @('lemma1') is just the formal translation of the generalized
  @('DO') @('loop$') we wrote in the earlier version of @('lemma1').</p>

  <p>Next we prove &ldquo;lemma 2&rdquo; equating the recursive function with
  the (generalized) specification.  This theorem does not involve @('loop$')
  and its proof should be utterly familiar to you.</p>

  @({
  (defthm lemma2
    (implies (and (natp n)
                  (natp ans0))
             (equal (copy-nat-ac n ans0)
                    (+ n ans0))))
  })

  <p>Finally, we prove our main theorem.</p>

  @({
  (defthm main
    (implies (natp n)
             (equal (loop$ with i = n
                           with ans = 0
                           do
                           (if (zp i)
                               (return ans)
                               (progn (setq ans (+ 1 ans))
                                      (setq i (- i 1)))))
                    n)))
  })

  <p>The proof rewrites the &ldquo;pretty&rdquo; @('do-body') @('lambda') into
  the normal form, @('lemma1') rewrites the new form of the @('loop$') after
  instantiating @('ans0') to @('0'), to @('(copy-nat-ac n 0)'), then
  @('lemma2') hits that to @('(+ n 0)'), and arithmetic does the rest.</p>

  <p>As we noted, our recipe is overly rigid.  Here is another sequence of
  events that proves @('main').  The experienced user realizes that the
  generalized @('DO') @('loop$') will in fact suggest the appropriate induction
  to ACL2.  So no special function is introduced.  Furthermore, the user
  &mdash; who has proved several theorems about @('loop$')s involving @('IF')
  and @('ZP') will know how to write the normal form.  That user would just do
  this.</p>

  @({
  (defthm lemma
    (implies
     (and (natp n) (natp ans0))
     (equal (loop$ with i = n
                   with ans = ans0
                   do
                   (if (integerp i)
                       (if (< 0 i)
                           (progn (setq ans (+ 1 ans))
                                  (setq i (- i 1)))
                           (return ans))
                       (return ans)))
            (+ n ans0))))

  (defthm main
    (implies (natp n)
             (equal (loop$ with i = n
                           with ans = 0
                           do
                           (if (zp i)
                               (return ans)
                           (progn (setq ans (+ 1 ans))
                                  (setq i (- i 1)))))
                    n)))
  })

  <p>For more details about rewriting @('lambda') objects you can leave the
  @('loop$') primer and read @(see rewrite-lambda-object) and @(see
  rewriting-versus-cleaning-up-lambda-objects).  But remember to come
  <b>back</b> here to @('lp-section-16')!</p>

  <p>Now go to @(see lp-section-17) (or return to the <see topic='@(url
  lp-section-0)'>Table of Contents</see>).</p>")

(defxdoc lp-section-17
  :parents (loop$-primer)
  :short "Challenge Proof Problems for @('DO') @('Loop$')s"
  :long "<h3>LP17: Challenge Proof Problems for @('DO') @('Loop$')s</h3>

  <p>In the following problems please write @('DO') @('loop$')s even though some
  of the problems can be solved with @('FOR') @('loop$')s.</p>

  <p>Our answers to the problems in this section are in @(see community-books)
  file @('demos/loop-primer/lp17.lisp').</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP17-1:</b> Write a @('DO') @('loop$') that reverses the list @('lst').
  For example, if @('lst') is @('(A B C)') the result should be @('(C B A)').
  Prove that your @('DO') @('loop$') is equal to @('(rev lst)'), where</p>

  @({
  (defun rev (x)
    (if (endp x)
        nil
        (append (rev (cdr x)) (list (car x)))))
  })

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP17-2:</b> Write a @('DO') @('loop$') that computes @('(member e
  lst)') and prove it correct.</p>

  <p><b>Hint:</b> Sometimes the main theorem suggests the right induction on
  its own.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP17-3:</b> Prove the following:</p>

  @({
  (defthm lp17-3-main
    (equal (loop$ with x = lst
                  with ans = 0
                  do
                   (cond ((endp x) (return ans))
                         (t (progn (setq ans (+ 1 ans))
                                   (setq x (cdr x))))))
           (len lst)))
  })

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP17-4:</b> Write a @('DO') @('loop$') that computes @('(nth n lst)'),
  when @('n') is a natural number.  Prove it correct.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP17-5:</b>  Prove the following.</p>

  @({
  (defthm lp17-5-main
    (implies (true-listp lst)
             (equal (loop$ with x = lst
                           with ans = nil
                           do
                           (cond
                            ((endp x) (return ans))
                            (t (progn (setq ans (append ans (list (car x))))
                                      (setq x (cdr x))))))
                    lst)))
  })

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP17-6:</b>  Prove the following.</p>

  @({
  (defthm lp17-6-main
    (implies (and (natp m)
                  (natp n))
             (equal (loop$ with i = m
                           with j = n
                           do
                           (if (zp i)
                               (return j)
                               (progn (setq i (- i 1))
                                      (setq j (+ j 1)))))
                    (+ m n))))
  })

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP17-7:</b> Write a @('DO') @('loop$') that computes @('(fact n)'), for
  natural number @('n'), where</p>

  @({
  (defun fact (n)
    (if (zp n)
        1
        (* n (fact (- n 1)))))
  })

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP17-8:</b> Write a @('DO') @('loop$') that scans a list of numbers,
  @('lst'), once and returns the sum of the elements and the sum of the
  squares (with @('sq') as defined below) of the elements of @('lst') as a cons
  pair.  E.g., given @('(1 2 3 4 5)') return @('(cons (+ 1 2 3 4 5) (+ (sq
  1) (sq 2) (sq 3) (sq 4) (sq 5)))') = @('(15 . 55)').</p>

  <p>Prove that your do loop$ is equal to</p>

  @({
  (cons (loop$ for e in lst sum e)
        (loop$ for e in lst sum (sq e)))
  })

  <p>Use the following definition of @('sq').</p>

  @({
  (defun sq (x) (* x x))
  })

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP17-9:</b> Define @('(partition-symbols lst)') with a @('DO')
  @('loop$') that partitions @('lst') into two lists, one containing all the
  symbols in @('lst') and the other containing all the non-symbols.  Return the
  cons of the two partitions and prove @('partition-symbols') correct.</p>

  <p>Hint: Since you are likely to collect the elements in reverse order, a
  suitable specification for these purposes is that @('partition-symbols')
  is equal to</p>

  @({
  (cons (rev (loop$ for e in lst when (symbolp e) collect e))
        (rev (loop$ for e in lst when (not (symbolp e)) collect e)))
  })

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP17-10:</b> Write a @('DO') @('loop$') that returns the list of
  naturals from @('n') down to @('0'), where @('n') is a natural.  For example,
  if @('n') is @('10') the answer is @('(10 9 8 7 6 5 4 3 2 1 0)').  Prove that
  when @('n') is a natural, your @('DO') @('loop$') returns the same thing as
  @('(loop$ for i from 0 to n collect (- n i))').</p>

  <p> Hints: Remember that in order for your &ldquo;lemma1&rdquo; to be applied
  in the proof of your main theorem it must match the rewritten lambda objects
  of the main theorem.  We've focused on matching the @('do-body') @('lambda').
  But it must also match the measure @('lambda').  So when you formulate your
  &ldquo;lemma1&rdquo;, pay attention to how your measure term normalizes under
  rewrite.  And by the way, if you use non-recursive functions in a term and
  you don't want them opened up when the lambda objects are rewritten in the
  main theorem, try disabling them.  (Some non-recursive functions cannot be
  disabled.  But another workaround is to define the whole measure as a
  function and disable it when appropriate.)</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p><b>LP17-11:</b> Define @('(all-pairs-do-loop$ imax jmax)') to compute the same
  @('(all-pairs imax jmax)') as was defined in section 11 (and below).
  But use @('DO') @('loop$s') instead of @('FOR') @('loop$')s in your
  definition of @('all-pairs-do-loop$').  Below we comment on what you
  should prove.</p>

  <p>The definition of @('all-pairs') was as follows.</p>

  @({
  (defun make-pair (i j)
    (declare (xargs :guard t))
    (cons i j))

  (defwarrant make-pair)

  (defun all-pairs-helper2 (i j jmax)
    (declare (xargs :measure (nfix (- (+ (nfix jmax) 1) (nfix j)))
                    :guard (and (natp i) (natp j) (natp jmax))))
    (let ((j (nfix j))
          (jmax (nfix jmax)))
      (cond
       ((> j jmax) nil)
       (t (cons (make-pair i j)
                (all-pairs-helper2 i (+ 1 j) jmax))))))

  (defun all-pairs-helper1 (i imax jmax)
    (declare (xargs :measure (nfix (- (+ (nfix imax) 1) (nfix i)))
                    :guard (and (natp i) (natp imax) (natp jmax))))
    (let ((i (nfix i))
          (imax (nfix imax)))
      (cond
       ((> i imax) nil)
       (t (append (all-pairs-helper2 i 1 jmax)
                  (all-pairs-helper1 (+ 1 i) imax jmax))))))

  (defun all-pairs (imax jmax)
    (declare (xargs :guard (and (natp imax) (natp jmax))))
    (all-pairs-helper1 1 imax jmax))
  })

  <p>Hints: In following our advice on proving do loop$s you will define
  functions that compute the same things as your @('DO') @('loop$')s.  In our
  solution we called these two functions @('apdh1') and @('apdh2'), where
  &ldquo;@('apdh')&rdquo; stands for @ldquo;@('all-pairs-do-helper')&rdquo;.
  You will prove two &ldquo;@('lemma1')&rdquo; theorems, one for each @('loop$').
  The second of those theorems will establish allow you to prove that your
  @('all-pairs-do-loop$') is @('apdh1').</p>

  <p>The next step in our recipe is to prove that the @('apdh1') is
  @('all-pairs') as above.  This will not involve @('loop$')s of any sort.
  It's just a normal proof about the relation between some recursively defined
  functions.  But we found this step surprisingly challenging!</p>

  <p>Since that second step does not involve @('loop$')s, you may consider your
  answer correct if you just prove the two &ldquo;@('lemma1')&rdquo; theorems!
  But if you want a non-@('loop$') challenge, finish the proof all the way to
  @('all-pairs').</p>

  <p>Now go to @(see lp-section-18) (or return to the <see topic='@(url
  lp-section-0)'>Table of Contents</see>).</p>")

(defxdoc lp-section-18
  :parents (loop$-primer)
  :short "Conclusion"
  :long "<h3>LP18: Conclusion</h3>

  <p>Here are two pieces of advice.</p>

  <p>First, if you can think of a good name for the concept implemented by a
  @('loop$') statement, use @('defun') to define that name.  This is especially
  the case if you intend to reason about that @('loop$') statement or to write
  more than one instance of it.</p>

  <p>For example, rather than write instances of</p>

  @({
  (loop$ for a in x as b in y sum (* a b))
  })

  <p>it is better to define @('(dot-product x y)') with that @('loop$') as its body
  and then write calls of @('dot-product').</p>

  <p>Basically, names are good as long as you can remember them.  They give you
  a place to hang lemmas and the lemmas match without having to think about
  rewriting lambdas, local variables, etc.  Not all @('loop$')s compute concepts
  with obvious, memorable names, but just because you can write
  &ldquo;anonymous&rdquo; iterations doesn't mean you should!</p>

  <p>Second, remember when you create a lemma intended to rewrite a @('loop$')
  statement you should normalize the body under your intended rewrite theory.
  As an experienced ACL2 user you would never write a lemma that tried to
  rewrite an @('endp') or @('nfix') or @('zp') term.  The lemma will never
  &ldquo;see&rdquo; such terms because the rewriter will have opened them up.
  You should apply that same kind of thinking when you write lemmas intended to
  rewrite @('loop$')s.</p>

  <p>That's it.  We can't think of anything else to say!  We urge you to resort
  to the ACL2 user's manual for further information.</p>

  <p>Some relevant topics are</p>

  <ul>
  <li>@(tsee loop$)</li>
  <li>@(see for-loop$)</li>
  <li>@(see do-loop$)</li>
  <li>@(tsee lambda$)</li>
  <li>@(see rewrite-lambda-object)</li>
  <li>@(see stating-and-proving-lemmas-about-loop$s)</li>
  </ul>

  <p>The End of the @('Loop$') Primer. (Return to the <see topic='@(url
  lp-section-0)'>Table of Contents</see>).</p>")

(defxdoc lp-background-review-2
  :parents (lp-section-1)
  :short "Review of @(tsee apply$) and related concepts"
  :long "<p>Below are some questions designed to review basic knowledge of
  @(tsee apply$) and related concepts used in the semantics of @('loop$').  For
  our answers see @(see lp-background-review-2-answers).</p>

  <p>But our answers are sometimes quite long and elaborate &mdash; more like
  little lectures on the subject than just answers.  So don't expect to
  reproduce our answers.  It's up to you to decide if you know this stuff.  As
  you use @('loop$'), ACL2 will print warnings and error messages about
  functions not having badges or warrants or expressions not being tame.  We
  don't want your reaction to be &ldquo;Ack! What's that all about?&rdquo; We
  want it to be at least &ldquo;Oh yes, I remember now.&rdquo; We recommend
  that after you've read and answered the questions, you read our answers even
  if you're pretty confident in your answers.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>Consider these events, executed as the first three events in new ACL2
  sessions.</p>

  @({
  (include-book "projects/apply/top" :dir :system)

  (defun sq (x)
    (declare (xargs :guard (natp x)))
    (* x x))

  (defun ghi (fn lst)
    (declare (xargs :guard (and (apply$-guard fn '(nil))
                                (true-listp lst))))
    (cond
      ((endp lst) nil)
      (t (cons (apply$ fn (list (car lst)))
               (ghi fn (cdr lst))))))
  })

  <p>The three events are executed without error and @('sq') and @('ghi') are
  admitted in @(':logic') mode.  By the way, we're naming certain functions in
  these reviews with consecutive letters of the alphabet, e.g., @('abc'),
  @('def'), @('ghi'), @('jkl'), @('mno'), etc.  These names are not mnemonic or
  acronyms.  Don't read anything into the names!  Note that unlike the review
  of elementary ACL2 features (see @(tsee lp-background-review-1)),
  here we define @('(sq x)') with a guard of @('(natp x)').  Both @('sq') and
  @('ghi') are guard verified upon admission.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>1: What is the value of @('(ghi 'sq '(1 2 3))')?  Hint: This is a trick
  question!</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>2: How do you assign a badge and warrant to @('sq')?</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>3: What is the name of the &ldquo;warrant function for @('sq')?&rdquo;  What does
  @('(warrant sq)') abbreviate?  What does @('(warrant sq)') imply about
  @('badge') and @('apply$')?</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>4: Can @('ghi') be warranted?  If so, what command do you type?</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>5: What is the name of the warrant function for @('ghi')?  Explain what
  the warrant for @('ghi') tells us.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>6: The following definition is admissible.  Can it be warranted?</p>

  @({
  (defun mno (x y z)
    (if (endp x)
        z
        (apply$ y
                (list (car x)
                      (mno (cdr x) y z)))))
  })

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>7: Is @('(equal (mno x 'cons y) (append x y))') a theorem?</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>8: The following @('defun') is admissible but cannot be warranted.
  Why?</p>

  @({
  (defun xyz (x) (apply$ x (list x)))
  })

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>9: Recall @('ghi') as defined at the beginning of this review.  Assume
  @('sq') has been warranted.  What is the value of @('(ghi 'sq '(1 2
  3))')?</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>10: Is @('(nat-listp (ghi 'sq lst))') a theorem?  If not, what theorem
  does this suggest?</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>11: What is the value of the term below?</p>

  @({
  (ghi (lambda$ (e) (ghi 'sq e))
       '((1 2 3)
         (4 5 6)
         (7 8 9)))
  })

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>12: Suppose you want to define @('jkl') to be something like what's shown
  below and you want the guards verified.</p>

  @({
  (defun jkl (lst)
    (declare (xargs :guard ...))
    (ghi (lambda$ (e) (ghi 'sq e)) lst)))
  })

  <p>Notice that the body of @('jkl') is the doubly nested @('ghi') term just
  tested, except now instead of applying it to a constant list we're applying
  it to the argument of @('jkl').</p>

  <p>What is the appropriate @(':')@(tsee guard) and do you have to make other
  modifications to the suggested @('defun') of @('jkl')?</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>13: Can @('jkl') be warranted?</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>14: Is this a theorem?  If not, what theorem does it suggest?</p>

  @({
  (implies (nat-listp-listp lst)
           (nat-listp-listp (jkl lst)))
  })

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>See @(see lp-background-review-2-answers) for our answers.  If
  your answers basically agree with ours we think you're ready to learn about
  @('loop$'), so go back to the @(see loop$-primer).  Otherwise, we strongly
  recommend that you read @(see introduction-to-apply$) and then @(tsee apply$)
  before reading about @('loop$').</p>

  <p>(Return to the <see topic='@(url lp-section-0)'>Table of
  Contents</see>.)</p>")

(defxdoc lp-background-review-2-answers
  :parents (lp-section-1)
  :short "Answers to the review of @(tsee apply$) and related concepts"
  :long "<p>Below are our answers to the Review of @(tsee apply$) and related
  concepts.  If your answers basically agree with ours, we think you're ready
  to follow the discussion in @(tsee loop$-primer).  If not, we recommend that
  you read @(see introduction-to-apply$) and then @(tsee apply$) before reading
  about @('loop$').</p>

  <p>But our answers are sometimes quite long and elaborate &mdash; more like
  little lectures on the subject than just answers.  So don't expect to
  reproduce our answers.  It's up to you to decide if you know this stuff.  As
  you use @('loop$'), ACL2 will print warnings and error messages about
  functions not having badges or warrants or expression not being tame.  We
  don't want your reaction to be &ldquo;Ack! What's that all about?&rdquo;  We want it to
  be at least &ldquo;Oh yes, I remember now.&rdquo;  So we recommend that you read these
  little mini-lectures in full.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>Consider these events, executed as the first three events in new ACL2
  sessions.</p>

  @({
  (include-book "projects/apply/top" :dir :system)

  (defun sq (x)
    (declare (xargs :guard (natp x)))
    (* x x))

  (defun ghi (fn lst)
    (declare (xargs :guard (and (apply$-guard fn '(nil))
                                (true-listp lst))))
    (cond
      ((endp lst) nil)
      (t (cons (apply$ fn (list (car lst)))
               (ghi fn (cdr lst))))))
  })

  <p>The three events are executed without error and @('sq') and @('ghi') are
  admitted in @(':logic') mode.  By the way, we're naming certain functions in
  these reviews with consecutive letters of the alphabet, e.g., @('abc'),
  @('def'), @('ghi'), @('jkl'), @('mno'), etc.  These names are not mnemonic or
  acronyms.  Don't read anything into the names!  Note that unlike the review
  of elementary ACL2 features (see @(tsee lp-background-review-1)),
  here we define @('(sq x)') with a guard of @('(natp x)').  Both @('sq') and
  @('ghi') are guard verified upon admission.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>1: What is the value of @('(ghi 'sq '(1 2 3))')?  Hint: This is a trick
  question!</p>

  <p>Answer: Note that @('ghi') is a @(see scion) of @('apply$').  It calls
  @('apply$'), passing in the first argument of @('ghi') as the &ldquo;function&rdquo; to
  @('apply$').  The evaluation of the above term fails with an error message
  because @('sq') is a user-defined @(':')@(tsee logic) mode function but has
  not been @(see warrant)ed (see @(tsee defwarrant)).  @(':Logic') mode
  functions must be warranted to be applied (with @('apply$')) at the top-level
  of the ACL2 read-eval-print loop.  Furthermore, if you ever try to prove a
  theorem whose proof requires expansion of the applications (with @('apply$'))
  of such functions, their warrants must be provided as hypotheses.  We'll get
  to that later.</p>

  <p>By the way, @(':')@(tsee program) mode functions must be @(tsee
  badge)d (see @(tsee defbadge)) to be applied at the top-level, but they need
  not be warranted (because @(':program') mode functions cannot be warranted or
  used meaningfully in conjectures to be proved).  See @(see
  guarantees-of-the-top-level-loop) for a discussion of the badge and warrant
  restrictions enforced by top-level evaluation.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>2: How do you assign a badge and warrant to @('sq')?</p>

  <p>Answer: @('(defwarrant sq)').</p>

  <p>@(tsee Defwarrant) assigns both a badge and a warrant to its argument, which
  must be a @(':logic') mode function satisfying certain restrictions on how it
  uses its arguments and how the termination of the function is justified.  If the
  function cannot be badged or cannot be warranted, an error is printed.</p>

  <p>@(tsee Defbadge) just assigns a badge and can work on @(':program') or
  @(':logic') mode functions.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>3: What is the name of the &ldquo;warrant function for @('sq')?&rdquo;  What does
  @('(warrant sq)') abbreviate?  What does @('(warrant sq)') imply about
  @('badge') and @('apply$')?</p>

  <p>Answer: The warrant function for @('sq') is named @('apply$-warrant-sq'),
  which is a 0-ary predicate.  @('(Warrant sq)') is just an abbreviation for a
  call of @('apply$-warrant-sq') and if more than one function symbol appears
  after the symbol @('warrant') then it expands to the conjunction of each of
  their predicates.  We'll show an example later.</p>

  <p>@('Apply$-warrant-sq') is introduced as a constrained function using
  @(tsee defun-sk).  Here is the event in question, but the details here are
  not critical to the present discussion.</p>

  @({
  (defun-sk apply$-warrant-sq ()
    (forall (args)
      (and
       (equal (badge-userfn 'sq) '(apply$-badge 1 1 . t))
       (equal (apply$-userfn 'sq args)
              (sq (car args)))))
    :constrain t)
  })

  <p>What is critical is the role that @('(apply$-warrant-sq)') plays in the
  following theorem, which is proved as a @(':')@(tsee rewrite) rule by
  @('(defwarrant sq)').</p>

  @({
  (defthm apply$-sq
    (implies (force (apply$-warrant-sq))
             (and (equal (badge 'sq)
                         '(apply$-badge 1 1 . t))
                  (equal (apply$ 'sq args)
                         (sq (car args))))))
  })

  <p>which allows the prover to reduce @('(badge 'sq)') to @('(apply$-badge 1 1
  . t)') and to reduce any instance of @('(apply$ 'sq args)') to @('(sq (car
  args))').</p>

  <p>The @(tsee badge) of @('sq') tells the prover that @('sq') is a function
  of one argument that returns one result.  The &ldquo;@(' . t')&rdquo; means &ldquo;all the
  arguments are ordinary objects,&rdquo; i.e., never treated like &ldquo;functions.&rdquo;</p>

  <p>The second part of the rule above will reduce the typical application of
  @('sq'), e.g., @('(apply$ 'sq (list e))'), to @('(sq e)').</p>

  <p>Finally, note that name of the rule is @('apply$-sq'), both the @('badge')
  and @('apply$') reductions are conditional on the warrant hypothesis for
  @('sq'), and that the warrant hypothesis is @(tsee force)d.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>4: Can @('ghi') be warranted?  If so, what command do you type?</p>

  <p>Answer: Yes!  Just type @('(defwarrant ghi)').</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>5: What is the name of the warrant function for @('ghi')?  Explain what
  the warrant for @('ghi') tells us.</p>

  <p>Answer: The warrant function for @('ghi') is named
  @('apply$-warrant-ghi').  @('(warrant ghi)') abbreviates
  @('(apply$-warrant-ghi)'), and, by the way, @('(warrant sq ghi ...)') expands
  to</p>

  @({
  (and (apply$-warrant-sq)
       (apply$-warrant-ghi)
       ...).
  })

  <p>The rule @('apply$-ghi') is proved by @('defwarrant').</p>

  @({
  (defthm apply$-ghi
    (and (implies (force (apply$-warrant-ghi))
  		(equal (badge 'ghi)
  		       '(apply$-badge 2 1 :fn nil)))
         (implies (and (force (apply$-warrant-ghi))
  		     (tamep-functionp (car args)))
  		(equal (apply$ 'ghi args)
  		       (ghi (car args) (car (cdr args)))))))
  })

  <p>Notice that @('apply$-ghi') is really two @(':rewrite') rules, both
  conditioned on the forced warrant for @('ghi').</p>

  <p>The first rule tells us what the @(tsee badge) of @('ghi') is.  In
  particular we see that the first argument of @('ghi') has &ldquo;@(see ilk)&rdquo;
  @(':')@('fn'), which means that argument is treated as a function and can
  eventually be applied with @('apply$').  Arguments of ilk @(':fn') are never
  treated as ordinary objects.  The badge of @('ghi') also tells us the second
  argument has ilk @('nil'), which means it is an ordinary object (and is never
  treated as a function).  The details are in @(tsee defbadge).</p>

  <p>Note that the second conjunct of the @('apply$-ghi') rule above rewrites
  instances of @('(apply$ 'ghi args)') and would rewrite @('(apply$ 'ghi (list
  x y))') to @('(ghi x y)').  However, it can only be used if the first
  argument passed to @('ghi'), namely @('x') above, is a @(see tame) function.
  Ilks, warrants, and tameness are concepts that are critical to the soundness
  of ACL2's handling of @('apply$').  For details see @(tsee apply$).</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>6: The following definition is admissible.  Can it be warranted?</p>

  @({
  (defun mno (x y z)
    (if (endp x)
        z
        (apply$ y
                (list (car x)
                      (mno (cdr x) y z)))))
  })

  <p>Answer: Yes.  Its badge is determined to be @('(apply$-badge 3 1 nil :fn
  nil)').</p>

  <p>For example,</p>

  @({
  (mno '(1 2 3) 'cons '(4 5 6))
  =
  (cons 1 (mno '(2 3) 'cons '(4 5 6)))
  =
  (cons 1 (cons 2 (mno '(3) 'cons '(4 5 6))))
  =
  (cons 1 (cons 2 (cons 3 (mno 'nil 'cons '(4 5 6)))))
  =
  (cons 1 (cons 2 (cons 3 '(4 5 6))))
  =
  '(1 2 3 4 5 6)
  })

  <p>In fact, @('mno') is more often named &ldquo;@('foldr')&rdquo; in the functional
  programming literature.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>7: Is @('(equal (mno x 'cons y) (append x y))') a theorem?</p>

  <p>Answer: Yes!  You might think we need to add the warrant hypothesis for
  @('cons') since @('(apply$ 'cons ...)') must be expanded to do the proof.
  However, most ACL2 primitives, like @('cons'), are built into the definition
  of @('apply$') and warrants are not necessary for them.  In fact, the
  primitives don't have warrant functions.  E.g., @('(apply$ 'cons (list x
  y))') is @('(cons x y)'), unconditionally.  The complete list of @('apply$')
  primitives may be exhibited by evaluating</p>

  @({
  (append '(BADGE TAMEP TAMEP-FUNCTIONP SUITABLY-TAMEP-LISTP
                  APPLY$ EV$)
          (strip-cars *badge-prim-falist*)).
  })

  <p>However, <i>user-defined function symbols</i> need warrants in order to be
  applied (with @('apply$')).  But not all user-defined symbols can be
  warranted.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>8: The following @('defun') is admissible but cannot be warranted.
  Why?</p>

  @({
  (defun xyz (x) (apply$ x (list x)))
  })

  <p>Answer: It is impossible to classify the argument @('x').  Is it a
  function or is it an ordinary object?  It's used both ways.  @('(Defwarrant
  xyz)') fails.</p>

  <p>In order for @('apply$') to be able to handle a function symbol certain
  restrictions must hold.  These restrictions guarantee that there is a model
  that makes all warrants true.  Here's a way to think about it.  Imagine that
  @('apply$') is defined as a big case analysis that enumerates all the
  functions that @('apply$') can handle and calls them appropriately.  That big
  definition of @('apply$') has some measure that explains why it terminates
  &mdash; a fairly messy measure given that @('apply$') can all @('ghi') which
  calls @('apply$').  Now imagine you want to define a new function, e.g.,
  @('xyz'), and change the definition of that big @('apply$') to include all
  the old functions plus @('xyz').  You'll need to weave the measure of
  @('xyz') into the measure of the big @('apply$').  @('Defwarrant') enforces
  restrictions that tell us this is possible.  Of course, the restrictions are
  overly restrictive: to be perfect @('defwarrant') would have to solve the
  halting problem.</p>


  <p>While the failure of @('(defwarrant xyz)') prevents us from being able to
  use @('apply$') to apply @('xyz'), it is possible to evaluate some calls of
  @('xyz') and to prove theorems about them.</p>

  @({
  (thm
    (equal (xyz '(lambda (x) (len x))) 3)
  })

  <p>In the proof of the theorem above, @('xyz') applied the given @('lambda')
  object to itself and computed that its length is 3.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>9: Recall @('ghi') as defined at the beginning of this review.  Assume
  @('sq') has been warranted.  What is the value of @('(ghi 'sq '(1 2
  3))')?</p>

  <p>Answer: @('(1 4 9)').</p>

  <p>Recall that an earlier question established that @('ghi') can be warranted
  and one might think warranting @('ghi') is necessary for @('(ghi 'sq '(1 2
  3))') to be evaluated without error.  But that's untrue.  @('Ghi') is not
  being applied (with @('apply$')) here, so whether it has been warranted or
  not is irrelevant.  However, @('sq') is being applied.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>10: Is @('(nat-listp (ghi 'sq lst))') a theorem?  If not, what theorem
  does this suggest?</p>

  <p>Answer: No, it's not a theorem as written.  For example @('(ghi 'sq '(-1/2
  #c(0 1)))') has the value @('(1/4 -1)'), although to get that value computed
  by the top-level read-eval-print loop you have to turn off guard
  checking (see @(tsee set-guard-checking)).</p>

  <p>The following is a theorem.</p>

  @({
  (implies (and (warrant sq)
                (nat-listp lst))
           (nat-listp (ghi 'sq lst)))
  })

  <p>The @('warrant') hypothesis for @('sq') is necessary because to prove
  anything interesting about @('(apply$ 'sq ...)') we need the warrant for
  @('sq').  The @('nat-listp') hypothesis is necessary because otherwise
  @('sq') may not return a natural number.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>11: What is the value of the term below?</p>

  @({
  (ghi (lambda$ (e) (ghi 'sq e))
       '((1 2 3)
         (4 5 6)
         (7 8 9)))
  })

  <p>Answer: @('((1 4 9) (16 25 36) (49 64 81))').</p>

  <p>@(tsee Lambda$) is an interesting ACL2 feature.  It translates the body
  term and constructs a @('lambda') object suitable for @('apply$').</p>

  <p>The @('ghi') term above is also interesting.  It shows that the outer call
  of @('ghi') can successfully @('apply$') the @('lambda') object which itself
  calls @('ghi') on @('sq').</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>12: Suppose you want to define @('jkl') to be something like what's shown
  below and you want the guards verified.</p>

  @({
  (defun jkl (lst)
    (declare (xargs :guard ...))
    (ghi (lambda$ (e) (ghi 'sq e)) lst)))
  })

  <p>Notice that the body of @('jkl') is the doubly nested @('ghi') term just
  tested, except now instead of applying it to a constant list we're applying
  it to the argument of @('jkl').</p>

  <p>What is the appropriate @(':')@(tsee guard) and do you have to make other
  modifications to the suggested @('defun') of @('jkl')?</p>

  <p>Answer: First, we define a predicate that recognizes a list of
  @('nat-listp')s, i.e., a list of lists, where each element of each of the
  inner lists is a natural number.</p>

  @({
  (defun nat-list-listp (lst)
    (declare (xargs :guard (true-listp lst)))
    (if (endp lst)
        t
        (and (nat-listp (car lst))
             (nat-list-listp (cdr lst)))))
  })

  <p>We could warrant @('nat-list-listp') with @('(defwarrant
  nat-list-listp)') if we wanted to, but because it is only used in a guard
  below, a warrant is not necessary.  If we intend to apply it with @('apply$')
  we would need a warrant and we can always warrant it when needed.</p>

  <p>We can then define @('jkl') with the :@('guard') shown below.  The
  @('true-listp') conjunct of the guard below is necessary because
  @('nat-list-listp') has @('true-listp') as its guard.  But note that we also
  modified the @(tsee lambda$) expression to express the guard on its local
  variable @('e').</p>

  @({
  (defun jkl (lst)
    (declare (xargs :guard (and (true-listp lst)
  			      (nat-list-listp lst))))
    (ghi (lambda$ (e)
                  (declare (xargs :guard (nat-listp e)))
                  (ghi 'sq e))
         lst))
  })

  <p>@('Jkl') is guard verified upon admission.  Consider what that means.  In
  particular, every time @('sq') is called it is called on something satisfying
  the guard of @('sq').  The guard proof obligations generated for a nest of
  functions using @('apply$') can be quite messy.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>13: Can @('jkl') be warranted?</p>

  <p>Answer: Yes.  @('(defwarrant jkl)') succeeds.  A key observation is that
  the @('lambda$') expression in its definition is a @('tame') function (see
  @('tame')).  That is syntactically determined because the body of the
  @('lambda$') is @('(ghi 'sq e)'), @('ghi') requires a tame function as its
  first argument, and @('sq') is a tame function.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>14: Is this a theorem?  If not, what theorem does it suggest?</p>

  @({
  (implies (nat-list-listp lst)
           (nat-list-listp (jkl lst)))
  })

  <p>Answer: It is not quite a theorem as written.  We need to add warrant
  hypotheses for the functions being applied with @('apply$').  Note that
  @('jkl') is not being applied, so we don't need its warrant.  The outer
  @('ghi') in the definition of @('jkl') is also not being applied.  But the
  @(tsee lambda$) expression passed as an argument to the outer @('ghi') is
  being applied by the outer @('ghi'), and to evaluate the body of that
  @('lambda') object we @('apply$') @('ghi'), so we need the warrant for
  @('ghi') there.  Furthermore, that inner @('ghi') will apply @('sq').  So we
  need the warrant for that.</p>

  <p>Thus, the following is indeed a theorem.</p>

  @({
  (implies (and (warrant ghi sq)
                (nat-list-listp lst))
           (nat-list-listp (jkl lst)))
  })

  <p>For some heuristic advice on how to figure out the necessary warrants, see
  the section &ldquo;Determining the Necessary Warrants&rdquo; in see @(tsee
  warrant).</p>

  <p>However, if you omit the warrant hypotheses ACL2 will often &ldquo;remind&rdquo; you
  at the end of failed proof attempts by exhibiting checkpoints derived from
  forcing the warrants when @('apply$') rules are applied.  If the warrants are
  omitted in this particular theorem checkpoints require proving both
  @('(apply$-warrant-sq)') and @('(apply$-warrant-ghi)').</p>

  <p>Finally, one might worry that it is impossible for all the listed warrants
  to be true at once, so perhaps listing a bunch of warrants might make your
  theorems vacuously valid.  But @('defwarrant') ensures that there is a model
  of the ACL2 logic in which all warrants are valid.  Thus, adding warrant
  hypotheses in no way makes your theorems less meaningful.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>If your answers basically agree with ours you should proceed on to @(see
  lp-section-2).  Otherwise, we strongly recommend that you read @(see
  introduction-to-apply$) and then @(tsee apply$) before reading about
  @('loop$').</p>

  <p>(Return to the <see topic='@(url lp-section-0)'>Table of
  Contents</see>.)</p>")

(defxdoc lp-background-review-1
  :parents (lp-section-1)
  :short "Background review of basic ACL2 knowledge"
  :long "<p>Here are some questions to review basic features of ACL2.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>Consider the expression below and answer the following questions about it,
  without running ACL2!  We're looking for informal answers largely in
  agreement with ours, not perfect answers.  If you want to see the questions
  together with our answers, see @(see
  lp-background-review-1-answers).</p>

  @({
  (defun abc (x)
    (declare (xargs :mode :program
                    :guard (true-listp x)))
    (cond
     ((endp x) nil)
     (t (cons (cons '? (car x))
              (abc (cdr x))))))
  })

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>1: Informally, what happens if you type that expression at the
  top-level of the ACL2 read-eval-print loop?</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>2: More formally, how does the utterance above affect the ACL2
  logic?</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>3: A little bit of Lisp knowledge will tell you that all terms are either
  variables, constants (usually quoted), or calls of functions, where calls are
  of the form @('(fn a1 ... an)'), where @('fn') is a function symbol or
  @('lambda') object that takes @('n') arguments and the @('ai') are terms.
  But the @('cond') expression above is not of this form.  @('Cond') is a macro
  that translates into a formal term.  What formal term does it translate
  to?  And if you didn't know, how would you find out?</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>4: Let @('x') be the object that prints as @('((A . 1) (B . 2) (C
  . 3))').  What is the value of @('(car x)') or is that a nonsensical
  question?  Several of the questions below are nonsensical!</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>5: Given the value of @('x') in question 4, what is the value of
  @('(true-listp x)')?</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>6: Given the value of @('x') in question 4, what is the value of @('(cons
  '? (car x))')?</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>7: Given the value of @('x') in question 4, what is the value of @('(cdr
  x)')?</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>8: Recall we defined @('abc') above.  What is the value @('(abc '((a
  . 1) (b . 2) (c . 3)))')?</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>9: What is the difference between @(''((a . 1) (b . 2) (c . 3))') and
  @('((A . 1) (B . 2) (C . 3))')?</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>10: What is the value of @('(abc ((a . 1) (b . 2) (c
  . 3)))')?</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>11: How would you explain what @('abc') is, i.e., how it &ldquo;works&rdquo; or
  what it &ldquo;does?&rdquo;</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>12: What is the value of @('(abc 3 4 5)')?</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>13: What is the value of @('(abc '(3 . 4))')?</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>14: How do you get ACL2 to print the value of @('(abc '(3 . 4))')?</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>15: How can you upgrade @('abc') from a @(':program') mode function to
  a @(':logic') mode function?</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>16: What is the axiom added to ACL2 when @('abc') is upgraded?</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>17: Is @('(true-listp (abc x))') a theorem in ACL2?</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>18: What would you type to get ACL2 to try to prove it?</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>19: How would you describe the behavior of the @(':logic') function
  @('def') below?  By the way, we're naming certain functions in these reviews
  with consecutive letters of the alphabet, e.g., @('abc'), @('def'), @('ghi'),
  @('jkl'), @('mno'), etc.  These names are not mnemonic or acronyms.  Don't
  read anything into the names!</p>

  @({
  (defun def (x)
    (if (endp x)
        nil
        (append (def (cdr x)) (list (car x)))))
  })

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>20: Define @('sq') to square a number.  E.g., @('(sq 9)') returns @('81')
  and @('(sq -1/2)') returns @('1/4').</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>21: How would you describe the behavior of @('sq*') below?</p>

  @({
  (defun sq* (x)
    (if (endp x)
        nil
        (cons (sq (car x))
              (sq* (cdr x)))))
  })

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>22: What would you type to make ACL2 prove the following conjecture?</p>

  @({
  (equal (sq* (def x)) (def (sq* x)))
  })

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;
  <p>23:  Prove @('(nat-listp (ghi 0 max))'), where</p>

  @({
  (defun ghi (i max)
    (declare (xargs :measure (nfix (- (+ 1 (nfix max)) (nfix i)))))
    (let ((i (nfix i))
          (max (nfix max)))
      (cond ((> i max) nil)
            (t (cons i (ghi (+ 1 i) max))))))
  })

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>For our answers see @(see lp-background-review-1-answers).  If
  your answers don't basically agree with ours, you're probably not yet ready
  to read this material on @(see loop$).  We recommend that you read the
  topic, @(see recursion-and-induction).</p>

  <p>If your answers largely agree with ours, go back to the @(see
  lp-section-1).</p>

  <p>(Return to the <see topic='@(url lp-section-0)'>Table of
  Contents</see>.)</p>")

(defxdoc lp-background-review-1-answers
  :parents (lp-section-1)
  :short "Answers to background review of basic ACL2 knowledge"
  :long "@({
  (defun abc (x)
    (declare (xargs :mode :program
                    :guard (true-listp x)))
    (cond
     ((endp x) nil)
     (t (cons (cons '? (car x))
              (abc (cdr x))))))
  })

  ——————————

  <p>1: Informally, what happens if you type that expression at the
  top-level of the ACL2 read-eval-print loop?</p>

  <p>Answer: It defines @('abc') as a Lisp program.  Note the @('declare') that
  says the @(':mode') is @(':program').  By the way, when Lisp and ACL2 read
  symbols, like @('abc'), @('x'), @('declare'), etc., they automatically
  convert them to UPPERCASE.  So it doesn't matter if we write @('abc') or
  @('ABC'), or @('Abc'), etc.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>2: More formally, how does the utterance above affect the ACL2
  logic?</p>

  <p>Answer: It doesn't.  Defining a @(':program') introduces no axioms into
  the logic.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>3: A little bit of Lisp knowledge will tell you that all terms are either
  variables, constants (usually quoted), or calls of functions, where calls are
  of the form @('(fn a1 ... an)'), where @('fn') is a function symbol or
  @('lambda') object that takes @('n') arguments and the @('ai') are terms.
  But the @('cond') expression above is not of this form.  @('Cond') is a macro
  that translates into a formal term.  What formal term does the @('cond')
  expression translate to?  And if you didn't know, how would you find out?</p>

  <p>Answer: The expression</p>
  @({
  (cond
   ((endp x) nil)
   (t (cons (cons '? (car x))
            (abc (cdr x)))))
  })
  <p>translates to</p>
  @({
  (if (endp x)
      'nil
      (cons (cons '? (car x))
            (abc (cdr x))))
  })
  <p>To see the translation of an expression use @(tsee trans).</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>4: Let @('x') be the object that prints as @('((A . 1) (B . 2) (C . 3))').
  What is the value of @('(car x)') or is that a nonsensical question?  Several
  of the questions below are nonsensical!</p>

  <p>Answer: @('(car x)') is @('(A . 1)') if @('x') is @('((A . 1) (B . 2) (C
  . 3))').</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>5: Given the value of @('x') in question 4, what is the value of
  @('(true-listp x)')?</p>

  <p>Answer: @('T'), because @('x') is a nest of conses whose rightmost
  terminal is @('NIL').</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>6: Given the value of @('x') in question 4, what is the value of @('(cons
  '? (car x))')?</p>

  <p>Answer: @('(? A . 1)')</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>7: Given the value of @('x') in question 4, what is the value of @('(cdr
  x)')?</p>

  <p>Answer: @('((B . 2) (C . 3))')</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>8: What is the value @('(abc '((a . 1) (b . 2) (c . 3)))')?</p>

  <p>Answer: @('((? A . 1) (? B . 2) (? C . 3))')</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>9: What is the difference between @(''((a . 1) (b . 2) (c . 3))') and
  @('((A . 1) (B . 2) (C . 3))')?</p>

  <p>Answer: @(''((a . 1) (b . 2) (c . 3))') is a constant term that evaluates
  to the list @('((A . 1) (B . 2) (C . 3))').  The quote mark in front an
  object forms a term that evaluates to that object.  And remember, case is
  generally irrelevant in symbols.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>10: What is the value of @('(abc ((a . 1) (b . 2) (c
  . 3)))')?</p>

  <p>Answer: That's a nonsensical question.  @('(abc ((a . 1) (b . 2) (c
  . 3)))') is not a well-formed term.  For example, @('(a . 1)') is not a
  function symbol or a @('lambda') expression, or a macro.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>11: How would you explain what @('abc') is, i.e., how it &ldquo;works&rdquo; or
  what it &ldquo;does?&rdquo;</p>

  <p>Answer: The symbol @('ABC') is the name of a Lisp program that takes one
  argument and returns one result.  It can be run, but nothing can be proved
  about it because there are no axioms defining it.  When @('abc') is called on
  @('x') it copies the @('cdr')-chain of @('x'), adding the question mark
  symbol to each new element.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>12: What is the value of @('(abc 3 4 5)')?</p>

  <p>Answer: Nonsensical. @('ABC') takes only one argument, not three.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>13: What is the value of @('(abc '(3 . 4))')?</p>

  <p>Answer: Actually, it is @('((? . 3))'), but ACL2 won't evaluate @('(abc
  '(3 . 4))') in the default configuration of the top-level read-eval-print
  loop because @('(3 . 4)') is not a @(tsee true-listp).  The guard on @('ABC')
  stipulates that the argument to @('ABC') is &ldquo;supposed&rdquo; to be a
  @('true-listp').  So the read-eval-print loop causes a guard violation error.
  We explain why the value of @('(abc '(3 . 4))') is actually @('((? . 3))') in
  the next answer.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>14: How do you get ACL2 to compute and print the value of @('(abc '(3
  . 4))')?</p>

  <p>Answer: The top-level read-eval-print loop has a parameter that controls
  whether ACL2 checks the guards or not.  By default, that parameter is set to
  @('T'), meaning it does check guards.  But by executing
  @('(set-guard-checking nil)') the parameter is set to @('NIL') and then
  guards are not checked.  With that setting, ACL2 evaluation just ignores the
  guard and runs the body of the program.</p>

  <p>So here is how @('(abc '(3 . 4))') is evaluated.  First, it checks whether
  @(tsee endp) holds on @('(3 . 4)').  The definition of @('endp') is
  @('atom'), which means &ldquo;is not a @(tsee cons) pair,&rdquo; and @('(3 . 4)') is a
  @('cons') pair.  So the answer to the @('endp') test is @('NIL') and the
  execution of @('(abc '(3 . 4))') branches to the @('(cons (cons '? (car
  x)) (abc (cdr x)))'), where @('x') is @('(3 . 4)').</p>

  <p>But the @('car') and @('cdr') of the pair @('(3 . 4)') are @('3') and
  @('4') respectively.  So the value of @('(abc '(3 . 4))') is @('(cons (cons
  '? 3) (abc 4))').</p>

  <p>But what is the value of @('(abc 4)')?  @('(Endp 4)') is @('T') because
  @('4') is an atom.  So the value of @('(cons (cons '? 3) (abc 4))') is
  @('(cons (cons '? 3) NIL)'), which is printed as @('((? . 3))').</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>15: How can you upgrade @('abc') from a @(':program') mode function to
  a @(':logic') mode function?</p>

  <p>Answer: Invoke @(tsee verify-termination) like this @('(verify-termination abc)').</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>16: What is the axiom added to the ACL2 logic when @('abc') is
  upgraded?</p>

  <p>Answer:</p>
  @({
  <b>Definitional Axiom for ABC</b>
  (abc x)
  =
  (if (endp x)
      nil
      (cons (cons '? (car x))
            (abc (cdr x)))).
  })

  <p>Note that the guard is irrelevant in the logic.  @('(Abc x)') is always
  equal to the right-hand side of the axiom above (the &ldquo;body&rdquo; of @('abc')),
  regardless of what @('x') is.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>17: Is @('(true-listp (abc x))') a theorem in ACL2?</p>

  <p>Answer: Yes!  It may not seem so because the @('defun') of @('abc')
  mentions the @(':guard') of @('(true-listp x)') and yet the conjecture here
  doesn't constrain @('x').  But guards of ACL2 functions are logically
  irrelevant.  The Definitional Axiom added for @('abc') does not mention the
  guard.  So @('(true-listp (abc x))') is a theorem no matter what @('x')
  is!</p>

  <p>Proof of @('(true-listp (abc x))') by induction on @('x'):</p>
  @({
  Base Case: (atom x)                  ; i.e., x is not a consp
  (true-listp (abc x))
  =                                    ; def abc
  (true-listp (if (endp x) nil ...))
  =                                    ; def endp and (atom x).
  (true-listp (if T nil ...))
  =                                    ; axiom about IF
  (true-listp nil)
  =                                    ; def true-listp
  T

  Induction Step: (consp x)
  Induction Hyp:  (true-listp (abc (cdr x)))

  (true-listp (abc x))
  =                                    ; def abc
  (true-listp (if (endp x) nil (cons (cons '? (car x)) (abc (cdr x)))))
  =                                    ; def endp and (consp x)
  (true-listp (if NIL nil (cons (cons '? (car x)) (abc (cdr x)))))
  =                                    ; axiom about IF
  (true-listp (cons (cons '? (car x)) (abc (cdr x))))
  =                                    ; def true-listp
  (true-listp (abc (cdr x)))
  =                                    ; Induction Hyp
  T

  Q.E.D.
  })

  <p>If you ask ACL2 to do the proof (see the next question) its proof doesn't
  mention induction.  That's because when @('abc') was defined ACL2 does a
  little inductive reasoning to deduce the &ldquo;type&rdquo; of the output and deduced
  that it is always a @('true-listp').  That type inference essentially does
  the inductive proof above.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>18: What would you type to get ACL2 to try to prove it?</p>

  <p>Answer:</p>

  @({
  (thm (true-listp (abc x)))
  })
  <p>or</p>
  @({
  (defthm little-theorem-about-abc
    (true-listp (abc x)))
  })

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>19: How would you describe the behavior of the @(':logic') function
  @('def') below?  By the way, we're naming certain functions in these reviews
  with consecutive letters of the alphabet, e.g., @('abc'), @('def'), @('ghi'),
  @('jkl'), @('mno'), etc.  These names are not mnemonic or acronyms.  Don't
  read anything into the names!</p>

  @({
  (defun def (x)
    (if (endp x)
        nil
        (append (def (cdr x)) (list (car x)))))
  })

  <p>Answer: It reverses @('x'), i.e., it returns a list containing the
  elements of @('x') in reverse order.  E.g., @('(def '(a b c))') returns @('(C
  B A)').</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>20: Define @('sq') to square a number.  E.g., @('(sq 9)') returns @('81')
  and @('(sq -1/2)') returns @('1/4').</p>

  <p>Answer:</p>

  @({
  (defun sq (x) (* x x))
  })

  <p>We could add a declaration, like @('(declare (xargs :guard (rationalp
  x)))') or @('(declare (xargs :guard (acl2-numberp x)))').  But we've chosen
  to keep things simple here.</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>21: How would you describe the behavior of @('sq*') below?</p>

  @({
  (defun sq* (x)
    (if (endp x)
        nil
        (cons (sq (car x))
              (sq* (cdr x)))))
  })

  <p>Answer: It squares every element of @('x') and returns the list of those
  results in the same order.  E.g., @('(sq* '(1 2 3 -1/2 #c(0 1)))') is @('(1 4
  9 1/4) -1').</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>22: What would you type to make ACL2 prove the following conjecture?</p>

  @({
  (equal (sq* (def x)) (def (sq* x)))
  })

  <p>Answer:  To get ACL2 to try to prove the theorem you could type</p>

  @({
  (defthm sq*-def
    (equal (sq* (def x)) (def (sq* x))))
  })

  <p>But ACL2 would fail to find the proof unless you'd proved some lemmas
  about @('def').  You might see a &ldquo;checkpoint&rdquo; like</p>

  @({
  *** Key checkpoint under a top-level induction
      before generating a goal of NIL (see :DOC nil-goal): ***

  Subgoal *1/2''
  (IMPLIES (AND (CONSP X)
                (EQUAL (DEF (SQ* (CDR X)))
                       (SQ* (DEF (CDR X)))))
           (EQUAL (APPEND (SQ* (DEF (CDR X)))
                          (LIST (* (CAR X) (CAR X))))
                  (SQ* (APPEND (DEF (CDR X)) (LIST (CAR X))))))
  })

  <p>What would that suggest you do?</p>

  <p>What we'd do is prove the following lemma first and then try
  @('sq*-def').</p>

  @({
  (defthm sq*-append
    (equal (sq* (append a b))
           (append (sq* a) (sq* b))))
  })

  <p>When that lemma is available as a @(':')@(tsee rewrite) rule during the
  proof of @('sq*-def') the checkpoint above would be further simplified, the
  induction hypothesis of the @('sq*-def') conjecture would be used, and the
  proof of @('sq*-def') would succeed.</p>

  <p>The experienced ACL2 user would anticipate this in a simple problem
  like this one.  But in a messier problem the experienced user would just be
  emotionally prepared for the proof attempt to fail and inspect the checkpoints
  to try to figure out how to complete the proof.  See @(see the-method).</p>

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;
  <p>23:  Prove @('(nat-listp (ghi 0 max))'), where</p>

  @({
  (defun ghi (i max)
    (declare (xargs :measure (nfix (- (+ 1 (nfix max)) (nfix i)))))
    (let ((i (nfix i))
          (max (nfix max)))
      (cond ((> i max) nil)
            (t (cons i (ghi (+ 1 i) max))))))
  })

  <p>Answer:  You can't prove @('(nat-listp (ghi 0 max))') by induction
  with that @('0') in one of the controlling arguments.  You have to generalize
  first.</p>

  @({
  (defthm nat-listp-ghi-lemma
     (nat-listp (ghi i max)))

  (defthm nat-listp-ghi
     (nat-listp (ghi 0 max)))
  })

  &mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;&mdash;

  <p>That completes the answers to this review of basic ACL2 knowledge.  If
  your answers don't largely agree with ours, you're probably not yet ready to
  read the material in the @(see loop$-primer).  We recommend that you take the
  &ldquo;Recursion and Induction&rdquo; course <b>(which should be somehow
  linked in here!)</b>.</p>

  <p>(Return to the <see topic='@(url lp-section-0)'>Table of
  Contents</see>.)</p>")

(defxdoc loop$-recursion
  :parents (loop$)
  :short "Defining functions that recur from within @('FOR') @('loop$') expressions"
  :long "<h3>Examples</h3>
  @({
  (defun$ nat-treep (x)
    (declare (xargs :loop$-recursion t
                    :measure (acl2-count x)))
    (cond
     ((atom x) (natp x))
     (t (and (true-listp x)
             (eq (car x) 'NATS)
             (loop$ for e in (cdr x) always (nat-treep e))))))

  (defun$ copy-nat-tree (x)
    (declare (xargs :loop$-recursion t
                    :measure (acl2-count x)))
    (cond
     ((atom x)
      (if (natp x)
          (if (equal x 0)
              0
              (+ 1 (copy-nat-tree (- x 1))))
          x))
     (t (cons 'nats
              (loop$ for e in (cdr x) collect (copy-nat-tree e))))))
  })

  <p>Notice that @('nat-treep') and @('copy-nat-tree') each contain a simple
  @('FOR') @(tsee loop$) (also see @(see for-loop$)) in which the function
  being defined is called recursively.  @('Copy-nat-tree') is a little more
  complicated than @('nat-treep') because @('copy-nat-tree') also contains a
  recursive call outside of any @('loop$').  Notice also that both events
  specify the @(tsee xargs) @(':loop$-recursion t') and explicitly provide a
  @(':measure').  The usual other @('xargs') are optional but
  @(':loop$-recursion t') is required if recursion is used inside a @('FOR')
  @('loop$') and the measure must be made explicit.</p>

  <p>Recursion is not allowed inside a @('DO') @('loop$') expression.  In fact,
  ACL2 disallows the use of @(':loop$-recursion') in the @('xargs') of any
  definition whose body contains a @('DO') @('loop$').  So this topic is only
  about @('FOR') @('loop$')s.</p>

  <p>Some examples of @('loop$')-recursive definitions may be found in the book
  @('projects/apply/loop-recursion-examples.lisp').</p>

  <p><b>Warning:</b> We advise you to use @(tsee defun$) rather than @(tsee
  defun) when introducing a @(':logic') mode @('loop$')-recursive function.
  When a @('loop$')-recursive function is introduced it is assigned a badge.
  This is required because we cannot translate the body of a
  @('loop$')-recursive function without a badge.  However, no warrant is
  assigned by @('defun').  But it is impossible to reason about
  applications (with @(tsee apply$)) of unwarranted functions.  Indeed, it is
  even impossible to execute such applications in the top-level ACL2
  read-eval-print loop.  See @(see guarantees-of-the-top-level-loop).  So a
  @(':logic') mode @('loop$')-recursive function &mdash; which is guaranteed to
  involve applications of itself with @('apply$') &mdash; can't be reasoned
  about or executed (except on data not exercising the recursive calls inside
  @('loop$')s).  These inconveniences can be avoided by using @('defun$') when
  introducing @(':logic') mode @('loop$')-recursive functions because
  @('defun$') expands to a @('defun') followed by a @(tsee defwarrant).</p>

  <p><b>Warning:</b> Even though the functions defined above are recursive,
  ACL2 does not generate induction schemes for them!  If you want to do
  inductive proofs about @('loop$')-recursive functions you must provide a
  suitable @(':induction') hint.  In addition, to be provable by induction,
  theorems about @('loop$')-recursive functions must be suitably general.  This
  topic is discussed further in @(see loop$-recursion-induction).</p>

  <h3>Restrictions</h3>

  <p>If a function being defined exhibits recursion from within a @(tsee loop$)
  body or within the @('WHEN') or @('UNTIL') clauses of a @('loop$') in a
  @(tsee defun) of <i>fn</i>, then the @('defun') must include an @(tsee xargs)
  declaration with @(':loop$-recursion t').  In addition,</p>

  <ul>

  <li>the @('xargs') declaration must include an explicit @(':measure'),</li>

  <li><i>fn</i> must not be part of a @(tsee mutual-recursion) clique,</li>

  <li>every formal of <i>fn</i> must be ``ordinary,'' e.g., not of @(tsee ilk)
  @(':FN') or @(':EXPR'),</li>

  <li><i>fn</i> must return a single value,</li>

  <li><i>fn</i>'s measure must be of type @(tsee natp) or be a lexicographic
  combination of natural numbers as defined by the @('llist') function in the
  Community Books at @('books/ordinals/'),</li>

  <li><i>fn</i> must be @(tsee tame), which implies it may not take or
  return @(tsee state) or @(tsee stobj)s,</li>

  <li>every quoted @(tsee lambda) object in the body of <i>fn</i> must be
  well-formed (see @(tsee well-formed-lambda-objectp)), which implies that
  every such @('lambda') object is tame and every function symbol, including
  <i>fn</i>, used in each must have a @(tsee badge),</li>

  <li>every quoted @('lambda') object in the body of <i>fn</i> that calls
  <i>fn</i> recursively must occur as the first argument of a @('loop$') scion
  and <i>not</i> in some arbitrary scion,</li>

  <li>there is at least one recursive call of <i>fn</i> inside a quoted
  @('lambda') object which means that the @('loop$-recursion t') declaration
  was actually necessary, and</li>

  <li>the necessary measure conjectures (see below) must be proved.</li>

  </ul>

  <p>These restrictions make a little more sense if you reflect on what has to
  be done to check and admit a @('loop$')-recursive function.  First, we assume
  that most ACL2 functions are not @('loop$')-recursive.  So to keep
  @('defun')-processing as fast as possible, we require you to declare when you
  are using @('loop$') recursion.  That declaration triggers additional
  checks.</p>

  <p>But before checks can begin, we have to translate the body of <i>fn</i>
  and since @('loop$')s translate into calls of @('loop$') scions on quoted
  @('lambda')s and those must be tame, and since some of those @('lambda')s
  involve calls of <i>fn</i>, we must assign a badge to <i>fn</i> even before
  we have translated its body.  We assign a badge that declares <i>fn</i> to
  take the appropriate number of ordinary inputs, to return one result, and be
  tame.  We check those requirements after <i>fn</i> has been admitted.</p>

  <p>Because the measure guessing heuristics of ACL2 do not look for calls
  inside of quoted @('lambda')s, the measure must be explicitly declared even
  if it @('acl2-count').</p>

  <p>To find every recursive call in a quoted @('lambda') object those objects
  must all be well-formed.  If such an object occurs as the first argument of a
  @('loop$') scion then we know it is only applied to elements of the
  @('loop$') scion's target.  Given that, we can investigate whether the
  recursive calls in the @('lambda') object are on smaller things.  But if a
  recursive call were to occur in a quoted @('lambda') object that was passed
  to some other kind of scion, we have no way to know (without extensive
  analysis) to what it might be applied.</p>

  <p>Some of these restrictions could be lifted with more analysis and coding.
  For example, we could change the specification for the @(':loop$-recursion')
  @('xargs') keyword so that instead of taking on a Boolean value it takes on a
  badge.  Then we could tentatively assign that badge to <i>fn</i> before
  processing and check it afterwards.  Our current thinking is to ask users to
  live with these restrictions and let us see whether @('loop$')-recursion is
  useful (almost certainly it will be), whether the community can develop proof
  techniques and tools to reason about them as effectively as we reason about
  conventional recursive functions (we're optimistic), and whether investing
  time in lifting some of these restrictions is worth it given all the other
  ways we could improve ACL2.</p>

  <h3>Measure Conjectures</h3>

  <p>Measure conjectures must be generated for the recursive calls inside
  @('loop$') bodies.  (We also generate conjectures for the recursive calls the
  other @('loop$')-expression components, e.g., the @('WHEN') clause, exactly
  analogously, but we speak of the @('loop$') body only below.  We also focus
  on simple @('loop$')s here but the conjectures described generalize to fancy
  @('loop$')s.)  Given a recursive call inside the body of a @('loop$') with
  iteration variable <i>v</i>, we first generate a new variable symbol,
  <i>v'</i>.  Certain terms, e.g., tests and arguments to recursive calls, will
  be extracted from within the body and used in the measure conjecture.  We
  rename <i>v</i> to <i>v'</i> in these terms to distinguish occurrences of
  <i>v</i> outside the @('loop$') from those inside.  The measure conjecture
  requires us to prove that the given measure decreases, as usual.  But the
  ruling tests are those ruling the @('loop$'), conjoined with the hypothesis
  that <i>v'</i> is a member of the target, conjoined with the (renamed) tests
  from inside the body ruling the recursive call.</p>

  <p>Below is an example.  We show only the measure conjectures generated from
  inside the @('loop$') because there are two recursive calls in the @('loop$')
  body.</p>

  @({
  (defun$ fn (v)
    (declare (xargs :loop$-recursion t
                    :measure (acl2-count x)))
    (cond
     ((natp v)
      ...)
     ((true-listp v)
      (loop$ for v in (target v) sum
             (if (and (integerp v) (< v 0))
                 (fn (- v))
                 (fn v))))
     (t ...)))
  })

  <p>Note that @('v') used both as the formal of @('fn') and as the iterative
  variable of the @('loop$').  In the measure conjectures below, the iterative
  variable has been renamed to @('nv0').  Two measure conjectures are generated
  from within the @('loop$'):</p>

  @({
  (implies (and (not (natp v))
                (true-listp v)
                (member-equal nv0 (target v))
                (and (integerp nv0) (< nv0 0)))
           (o< (acl2-count (- nv0))
               (acl2-count v)))

  (implies (and (not (natp v))
                (true-listp v)
                (member-equal nv0 (target v))
                (not (and (integerp nv0) (< nv0 0))))
           (o< (acl2-count nv0) (acl2-count v)))
  })

  <p>Note that these conjectures require that when @('fn') is called from
  within the @('loop$') the argument is smaller than the initial value of the
  formal.  Notice also that there is no <i>a priori</i> restriction on the size
  of @('(target v)').  However, because of the way @('fn') is used inside this
  particular example @('loop$'), there are restrictions on the size of the
  elements of @('(target v)').  These conjectures, along with those generated
  from calls outside the @('loop$') are sufficient to guarantee that @('fn')
  always terminates.</p>

  <p><b>Note:</b> Careful readers might note that the way we handle measure
  conjectures for @('loop$')s differs from the way we handle guard conjectures
  for @('loop$')s.  In @(tsee loop$) we explained that @('loop$')s are
  translated into calls of @('loop$') @(tsee scion)s on quoted @(tsee lambda)
  objects and that the guard conjectures for the @('lambda') are insensitive to
  the context in which the object appeared.  But the measure conjectures are
  sensitive to the context: tests from outside the @('loop$') are present in
  the measure conjectures.  This is deliberate.  Guard conjectures are context
  insensitive because the implementation caches compiled @('lambda') objects
  without remembering the contexts in which they first occurred.  Thus, a
  @('lambda') object generated by a @('loop$') may be called on anything and we
  cannot guarantee that the input guard to the @('lambda') object will be
  satisfied.  <i>But we can guarantee that the computation carried out by the
  @('lambda') will terminate!</i> The @('lambda') object generated for @('fn')
  above terminates no matter what it is called on -- even if called on elements
  not in @('(target v)') -- because @('fn') terminates.</p>

  <p>Finally, recall that @('loop$')-recursive functions do not automatically
  suggest induction schemes and that special care must be taken when
  formulating inductively provable conjectures about them.  See @(see
  loop$-recursion-induction).</p>")

(defxdoc loop$-recursion-induction
  :parents (loop$)
  :short "Advice on inductive theorems about @(tsee loop$)-recursive functions"
  :long "<p><b>Warning:</b> This documentation topic is fairly preliminary
  because we do not have a lot of experience yet with @(tsee apply$), @(tsee
  loop$), and @(tsee loop$-recursion).  We assume here that readers are familiar
  with the topics cited above.</p>

  <h3>Definductor</h3>

  <p>The principles sketched here are illustrated concretely in the tutorial
  community book @('projects/apply/copy-nat-tree.lisp').  As noted in that
  book, the inductions are hinted manually so the reader can see from first
  principles what is involved.  However, in the book @('projects/apply/top') we
  provide a utility that sometimes automates the creation of the inductive hint
  function and associates it with the given @('loop$')-recursive function.  See
  @(tsee definductor).  The examples worked manually in @('copy-nat-tree.lisp')
  are recapitulated towards the end of
  @('projects/apply/definductor-tests.lisp'), without the manually provided
  hints.  In addition, the book
  @('projects/apply/loop-recursion-examples.lisp') gives some other examples of
  loop$-recursive functions and inductive theorems about them.</p>

  <h3>Some Basic Principles for Inductive Proofs about @('Loop$')-Recursive Functions</h3>

  <p>If ACL2 did not have @('loop$'), functions defined in terms of
  @('loop$')-recursion would have to be defined with @(tsee mutual-recursion).
  Reconsider the example presented in @(tsee loop$-recursion).</p>

  @({
  (defun$ nat-treep (x)
    (declare (xargs :loop$-recursion t
                    :measure (acl2-count x)))
    (cond
     ((atom x) (natp x))
     (t (and (true-listp x)
             (eq (car x) 'NATS)
             (loop$ for e in (cdr x) always (nat-treep e))))))

  (defun$ copy-nat-tree (x)
    (declare (xargs :loop$-recursion t
                    :measure (acl2-count x)))
    (cond
     ((atom x)
      (if (natp x)
          (if (equal x 0)
              0
              (+ 1 (copy-nat-tree (- x 1))))
          x))
     (t (cons 'nats
              (loop$ for e in (cdr x) collect (copy-nat-tree e))))))
  })

  <p>Without @('loop$') the latter function would have to be defined this way.
  We name it @('mr-copy-nat-tree'), where the ``@('mr')'' reminds us this is
  part of a mutually recursive clique.</p>

  @({
  (mutual-recursion
   (defun mr-copy-nat-tree (x)
     (cond
      ((atom x)
       (if (natp x)
           (if (equal x 0)
               0
               (+ 1 (mr-copy-nat-tree (- x 1))))
           x))
      (t (cons 'nats
               (mr-copy-nat-tree-list (cdr x))))))

   (defun mr-copy-nat-tree-list (x)
     (cond
      ((endp x) nil)
      (t (cons (mr-copy-nat-tree (car x))
               (mr-copy-nat-tree-list (cdr x)))))))
  })

  <p>Note that we define @('mr-copy-nat-tree') by copying the definition of
  @('copy-nat-tree') (renaming recursive calls appropriately) but replacing the
  use of @('loop$') in @('copy-nat-tree') with a call of a mutually-recursive
  function here called @('mr-copy-nat-tree-list').  We call
  @('mr-copy-nat-tree-list') the ``list counterpart'' of @('mr-copy-nat-tree').
  However, in general there may be more than just two functions in the clique
  and so we refer generically to @('mr-copy-nat-tree-list') as a ``co-member''
  of the clique.</p>

  <p>How would you prove theorems about @('mr-copy-nat-tree')?  Four principles
  are known to most ACL2 users of @('mutual-recursion').  These principles
  apply to @('loop$')-recursive functions as well as to mutually recursive
  ones.  We state them here in terms of both kinds of definitions.</p>

  <ul>

  <li>While simple recursive functions suggest ``appropriate'' inductions,
  mutually recursive functions and @('loop$')-recursive functions do not.  If
  you want to prove a theorem about such functions you have to arrange some
  kind of induction hint.</li>

  <li>You can't generally prove an isolated theorem about a single member of a
  mutually recursive clique or a @('loop$')-recursive function.  Instead, you
  must state a conjecture about every member of the clique, conjoin all those
  theorems together, and prove them inductively all at once.  Applied to
  proving a theorem about @('mr-copy-nat-tree') this advice means we must
  conjoin the theorem about that function with ``the same'' theorem about
  @('mr-copy-nat-tree-list'), and more generally with theorems about every
  co-member of the clique.  Of course, what we mean by ``the same'' theorem
  about different members of the clique depends on what each member contributes
  to the overall computation.  Applied to the @('loop$')-recursive function
  @('copy-nat-tree') this advice means we must simultaneously prove a theorem
  about every @('loop$') in the function.</li>

  <li>Inductively provable theorems must be sufficiently general.  When dealing
  with a mutually recursive clique, each conjunct must address itself to the
  ``general'' call of the co-member in question, e.g., to
  @('(mr-copy-nat-tree-list x)') not to the specific call inside
  @('mr-copy-nat-tree'), which is @('(mr-copy-nat-tree-list (cdr x))').  When
  dealing with a @('loop$')-recursive function, each conjunct must address
  itself to the general target, not to specific target in the @('loop$')
  recursive function.  In the case of the @('loop$')-recursive function
  @('copy-nat-tree') we need a conjunct about @('(loop$ for e in x
  collect (copy-nat-tree e))'), not about @('(loop$ for e in (cdr x)
  collect (copy-nat-tree e))').</li>

  <li>Finally, the induction scheme used must provide an inductive hypothesis
  about every recursive call of every co-member of the clique or, in the case
  of @('loop$')-recursion, about every recursive unwinding of each
  @('loop$').</li>

  </ul>

  <p><b>Remember:</b> Because @('loop$')-recursive functions call themselves
  recursively with @('apply$'), any theorem about a @('loop$') recursive
  function must almost certainly include a warrant hypothesis for that
  function!</p>

  <p>We illustrate these principles in the community book
  @('projects/apply/copy-nat-list.lisp').</p>")

(defxdoc loop-stopper
  :parents (rewrite)
  :short "Limit application of permutative rewrite rules"
  :long "<p>See @(see rule-classes) for a discussion of the syntax of the
 @(':loop-stopper') field of @(':')@(tsee rewrite) rule-classes.  Here we
 describe how that field is used, and also how that field is created when the
 user does not explicitly supply it.</p>

 <p>For example, the built-in @(':')@(tsee rewrite) rule
 @('commutativity-of-+'),</p>

 @({
  (implies (and (acl2-numberp x)
                (acl2-numberp y))
           (equal (+ x y) (+ y x))),
 })

 <p>creates a rewrite rule with a loop-stopper of @('((x y binary-+))').  This
 means, very roughly, that the term corresponding to @('y') must be ``smaller''
 than the term corresponding to @('x') in order for this rule to apply.
 However, the presence of @(tsee binary-+) in the list means that certain
 functions that are ``invisible'' with respect to @(tsee binary-+) (by default,
 @(tsee unary--) is the only such function) are more or less ignored when
 making this ``smaller'' test.  We are much more precise below.</p>

 <p>Our explanation of loop-stopping is in four parts.  First we discuss ACL2's
 notion of ``term order.''  Next, we bring in the notion of ``invisibility'',
 and use it together with term order to define orderings on terms that are used
 in the loop-stopping algorithm.  Third, we describe that algorithm.  These
 topics all assume that we have in hand the @(':loop-stopper') field of a given
 rewrite rule; the fourth and final topic describes how that field is
 calculated when it is not supplied by the user.</p>

 <p>ACL2 must sometimes decide which of two terms is syntactically simpler.  It
 uses a total ordering on terms, called the ``term order.''  Under this
 ordering constants such as @(''(a b c)') are simpler than terms containing
 variables such as @('x') and @('(+ 1 x)').  Terms containing variables are
 ordered according to how many occurrences of variables there are.  Thus @('x')
 and @('(+ 1 x)') are both simpler than @('(cons x x)') and @('(+ x y)').  If
 variable counts do not decide the order, then the number of function
 applications are tried.  Thus @('(cons x x)') is simpler than @('(+ x (+ 1
 y))') because the latter has one more function application.  Finally, if the
 number of function applications do not decide the order, a lexicographic
 ordering on Lisp objects is used.  See @(see term-order) for details.</p>

 <p>When the loop-stopping algorithm is controlling the use of permutative
 @(':')@(tsee rewrite) rules it allows @('term1') to be moved leftward over
 @('term2') only if @('term1') is smaller, in a suitable sense.  Note: The
 sense used in loop-stopping is <b>not</b> the above explained term order but a
 more complicated ordering described below.  The use of a total ordering stops
 rules like commutativity from looping indefinitely because it allows @('(+ b
 a)') to be permuted to @('(+ a b)') but not vice versa, assuming @('a') is
 smaller than @('b') in the ordering.  Given a set of permutative rules that
 allows arbitrary permutations of the tips of a tree of function calls, this
 will normalize the tree so that the smallest argument is leftmost and the
 arguments ascend in the order toward the right.  Thus, for example, if the
 same argument appears twice in the tree, as @('x') does in the @(tsee
 binary-+) tree denoted by the term @('(+ a x b x)'), then when the allowed
 permutations are done, all occurrences of the duplicated argument in the tree
 will be adjacent, e.g., the tree above will be normalized to @('(+ a b x
 x)').</p>

 <p>Suppose the loop-stopping algorithm used term order, as noted above, and
 consider the @(tsee binary-+) tree denoted by @('(+ x y (- x))').  The
 arguments here are in ascending term order already.  Thus, no permutative
 rules are applied.  But because we are inside a @('+-expression') it is very
 convenient if @('x') and @('(- x)') could be given virtually the same position
 in the ordering so that @('y') is not allowed to separate them.  This would
 allow such rules as @('(+ i (- i) j) = j') to be applied.  In support of this,
 the ordering used in the control of permutative rules allows certain unary
 functions, e.g., the unary minus function above, to be ``invisible'' with
 respect to certain ``surrounding'' functions, e.g., @(tsee +) function
 above.</p>

 <p>Briefly, a unary function symbol @('fn1') is invisible with respect to a
 function symbol @('fn2') if @('fn2') belongs to the value of @('fn1') in
 @(tsee invisible-fns-table); also see @(see set-invisible-fns-table), which
 explains its format and how it can be set by the user.  Roughly speaking,
 ``invisible'' function symbols are ignored for the purposes of the term-order
 test.</p>

 <p>Consider the example above, @('(+ x y (- x))').  The translated version of
 this term is @('(binary-+ x (binary-+ y (unary-- x)))').  The initial @(tsee
 invisible-fns-table) makes @(tsee unary--) invisible with respect to @(tsee
 binary-+).  The commutativity rule for @(tsee binary-+) will attempt to swap
 @('y') and @('(unary-- x)') and the loop-stopping algorithm is called to
 approve or disapprove.  If term order is used, the swap will be disapproved.
 But term order is not used.  While the loop-stopping algorithm is permuting
 arguments inside a @(tsee binary-+) expression, @(tsee unary--) is invisible.
 Thus, instead of comparing @('y') with @('(unary-- x)'), the loop-stopping
 algorithm compares @('y') with @('x'), approving the swap because @('x') comes
 before @('y').</p>

 <p>Here is a more precise specification of the total order used for
 loop-stopping with respect to a list, @('fns'), of functions that are to be
 considered invisible.  Let @('x') and @('y') be distinct terms; we specify
 when ``@('x') is smaller than @('y') with respect to @('fns').''  If @('x') is
 the application of a unary function symbol that belongs to @('fns'), replace
 @('x') by its argument.  Repeat this process until the result is not the
 application of such a function; let us call the result @('x-guts').  Similarly
 obtain @('y-guts') from @('y').  Now if @('x-guts') is the same term as
 @('y-guts'), then @('x') is smaller than @('y') in this order iff @('x') is
 smaller than @('y') in the standard term order.  On the other hand, if
 @('x-guts') is different than @('y-guts'), then @('x') is smaller than @('y')
 in this order iff @('x-guts') is smaller than @('y-guts') in the standard term
 order.</p>

 <p>Now we may describe the loop-stopping algorithm.  Consider a rewrite rule
 with conclusion @('(equiv lhs rhs)') that applies to a term @('x') in a given
 context; see @(see rewrite).  Suppose that this rewrite rule has a
 loop-stopper field (technically, the @(':heuristic-info') field) of @('((x1 y1
 . fns-1) ... (xn yn . fns-n))').  (Note that this field can be observed by
 using the command @(':')@(tsee pr) with the name of the rule; see @(see pr).)
 We describe when rewriting is permitted.  The simplest case is when the
 loop-stopper list is @('nil') (i.e., @('n') is @('0')); in that case,
 rewriting is permitted.  Otherwise, for each @('i') from 1 to @('n') let
 @('xi'') be the actual term corresponding to the variable @('xi') when
 @('lhs') is matched against the term to be rewritten, and similarly correspond
 @('yi'') with @('y').  If @('xi'') and @('yi'') are the same term for all
 @('i'), then rewriting is not permitted.  Otherwise, let @('k') be the least
 @('i') such that @('xi'') and @('yi'') are distinct.  Let @('fns') be the list
 of all functions that are invisible with respect to every function in
 @('fns-k'), if @('fns-k') is non-empty; otherwise, let @('fns') be @('nil').
 Then rewriting is permitted if and only if @('yi'') is smaller than @('xi'')
 with respect to @('fns'), in the sense defined in the preceding paragraph.</p>

 <p>It remains only to describe how the loop-stopper field is calculated for a
 rewrite rule when this field is not supplied by the user.  (On the other hand,
 to see how the user may specify the @(':loop-stopper'), see @(see
 rule-classes).)  Suppose the conclusion of the rule is of the form @('(equiv
 lhs rhs)').  First of all, if @('rhs') is not an instance of the left hand
 side by a substitution whose range is a list of distinct variables, then the
 loop-stopper field is @('nil').  Otherwise, consider all pairs @('(u . v)')
 from this substitution with the property that the first occurrence of @('v')
 appears in front of the first occurrence of @('u') in the print representation
 of @('rhs').  For each such @('u') and @('v'), form a list @('fns') of all
 functions @('fn') in @('lhs') with the property that @('u') or @('v') (or
 both) appears as a top-level argument of a subterm of @('lhs') with function
 symbol @('fn').  Then the loop-stopper for this rewrite rule is a list of all
 lists @('(u v . fns)').</p>

 <p><i>Remark.</i> The paragraph above mentions ``the conclusion of the rule''
 as @('(equiv lhs rhs)').  The rule's conclusion is actually produced from a
 naive version @('(equiv lhs0 rhs)') of the conclusion by expanding away all
 @(see lambda) applications in @('lhs0').  If @('lhs0') and @('lhs') are
 distinct (i.e., if there is any such lambda expansion) and also the
 loop-stopper field is calculated as @('nil') as described above, then a second
 attempt to calculate the loop-stopper is made using @('lhs0') in place of
 @('lhs').</p>")

(defxdoc lower-case-p
  :parents (characters acl2-built-ins)
  :short "Recognizer for lower case characters"
  :long "<p>@('(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').</p>

 <p>The @(see guard) for @('lower-case-p') states that its argument is a
 character.</p>

 <p>@('Lower-case-p') is a Common Lisp function.  See any Common Lisp
 documentation for more information.  Note that the value returned may depend
 on the host Lisp; see @(see soundness), specifically Example 1 in the Section,
 &ldquo;Examples of divergence among Lisp implementations&rdquo;.</p>

 @(def lower-case-p)")

(defxdoc lp
  :parents (ld)
  :short "The Common Lisp entry to ACL2"
  :long "<p>To enter the ACL2 @(see command) loop from Common Lisp, call the
 Common Lisp program @('lp') (which stands for ``loop,'' as in
 ``read-eval-print loop'' or ``@(see command) loop.'')  The ACL2 @(see command)
 loop is actually coded in ACL2 as the function @(tsee ld) (which stands for
 ``load'').  The @(see command) loop is just what you get by loading from the
 standard object input channel, @(tsee *standard-oi*).  Calling @(tsee ld)
 directly from Common Lisp is possible but fragile because hard lisp errors or
 aborts throw you out of @(tsee ld) and back to the top-level of Common Lisp.
 @('Lp') calls @(tsee ld) in such a way as to prevent this and is thus the
 standard way to get into the ACL2 @(see command) loop.  Also see @(see
 acl2-customization) for information on the loading of an initialization
 file.</p>

 <p>All of the visible functionality of @('lp') is in fact provided by @(tsee
 ld), which is written in ACL2 itself.  Therefore, you should see @(see ld) for
 detailed @(see documentation) of the ACL2 @(see command) loop.  We sketch it
 below, for novice users.</p>

 <p>Every expression typed to the ACL2 top-level must be an ACL2
 expression.</p>

 <p>Any ACL2 expression may be submitted for evaluation.  Well-formedness is
 checked.  Some well-formed expressions cannot be evaluated because they
 involve (at some level) undefined constrained functions (see @(see
 encapsulate)).  In addition, ACL2 does not allow ``global variables'' in
 expressions to be evaluated.  Thus, @('(car '(a b c))') is legal and evaluates
 to @('A'), but @('(car x)') is not, because there is no ``global context'' or
 binding environment that gives meaning to the variable symbol @('x').</p>

 <p>There is an exception to the global variable rule outlined above:
 single-threaded objects (see @(see stobj)) may be used as global variables in
 top-level expressions.  The most commonly used such object is the ACL2
 ``current state,'' which is the value of the variable symbol @(tsee state).
 This variable may occur in the top-level form to be evaluated, but must be
 passed only to ACL2 functions ``expecting'' @('state') as described in the
 documentation for @(tsee state) and for @(tsee stobj)s in general.  If the
 form returns a new @(see state) object as one of its values, then that is
 considered the new ``current'' @(see state) for the evaluation of the
 subsequent form.  See @(see state).</p>

 <p>ACL2 provides some support for the functionality usually provided by global
 variables in a read-eval-print loop, namely the saving of the result of a
 computation for subsequent re-use in another expression.  See @(see assign)
 and see @(see @).</p>

 <p>If the form read is a single keyword, e.g., @(':')@(tsee pe) or
 @(':')@(tsee ubt), then special procedures are followed.  See @(see
 keyword-commands).</p>

 <p>The @(see command) loop keeps track of the @(see command)s you have typed
 and allows you to review them, display them, and roll the logical @(see state)
 back to that created by any @(see command).  See @(see history).</p>

 <p>ACL2 makes the convention that if a top-level form returns three values,
 the last of which is an ACL2 @(see state), then the first is treated as a flag
 that means ``an error occurred,'' the second is the value to be printed if no
 error occurred, and the third is (of course) the new @(see state).  When ``an
 error occurs'' no value is printed.  Thus, if you execute a top-level form
 that happens to return three such values, only the second will be printed (and
 that will only happen if the first is @('nil')!).  See @(see ld) for
 details.</p>")

(defxdoc macro-aliases-table
  :parents (macros)
  :short "A @(see table) used to associate function names with macro names"
  :long "@({
 Example Form:
 (table macro-aliases-table 'append 'binary-append)
 })

 <p>This example associates the function symbol @(tsee binary-append) with the
 macro name @(tsee append).  As a result, the name @(tsee append) may be used
 as a runic designator (see @(see theories)) by the various theory functions.
 Thus, for example, it will be legal to write</p>

 @({
 (in-theory (disable append))
 })

 <p>as an abbreviation for</p>

 @({
 (in-theory (disable binary-append)).

 General Form:

 (table macro-aliases-table 'macro-name 'function-name)
 })

 <p>or more generally</p>

 @({
 (table macro-aliases-table macro-name-form function-name-form)
 })

 <p>where @('macro-name-form') and @('function-name-form') evaluate to values
 @('MAC') and @('FN'), subject to the following requirements.</p>

 <ul>

 <li>@('MAC') is a symbol that is a macro name.</li>

 <li>@('FN') is a symbol.</li>

 <li>@('FN') is either a function symbol or else a symbol that does not have a
 definition (a <i>new name</i>).  In particular, @('FN') is not a macro
 name.</li>

 </ul>

 <p>After admitting the @(see table) event displayed above, we may say that
 @('MAC') is a <i>macro-alias for</i> @('FN').</p>

 <h3>Further Explanation</h3>

 <p>See @(see table) for a general discussion of tables and the @('table')
 @(see event), which is used to manipulate tables.  The table, @(tsee
 macro-aliases-table), is an alist that can associate macro symbols with
 function symbols, so that macro names may be used as runic designators (see
 @(see theories) and discussion below).  For a convenient way to add entries to
 this @(see table), see @(see add-macro-alias), which allows the second
 argument to be, itself, a macro-alias.  To remove entries conveniently from
 the @(see table), see @(see remove-macro-alias).</p>

 <p>As hinted above, this @(see table) is used by theory functions; see @(see
 theories).  For example, in order that @('(disable append)') be interpreted as
 @('(disable binary-append)'), it suffices that @('(table macro-aliases-table
 'append 'binary-append)'), has been executed.  In fact, this @(see table) does
 indeed establish many of the macros provided by the ACL2 system as
 macro-aliases, such as establishing @(tsee append) as a macro-alias for @(tsee
 binary-append).  This only takes place when the macro is &ldquo;essentially
 the same thing as&rdquo; a corresponding function; for example, @('(append x
 y)') and @('(binary-append x y)') represent the same term, for any expressions
 @('x') and @('y').</p>

 <p>Note that the value @('FN') of @('function-name-form') (above) is allowed
 to be a symbol to be defined later as a function symbol.  The following
 examples illustrate some approaches that work and some that do not.</p>

 @({
 ;;;;;;;;;;
 ;;; Example 1: No errors, with function defined before setting the table.
 ;;;;;;;;;;

 (defun fn (x) x)
 (defmacro mac (x) (list 'fn x))
 (table macro-aliases-table 'mac 'fn) ; or (add-macro-alias mac fn)
 (in-theory (disable mac))

 ;;;;;;;;;;
 ;;; Example 2: No errors, with function defined after setting the table.
 ;;;;;;;;;;

 (defmacro mac (x) (list 'fn x))

 ; Legal, even though fn is not yet defined:
 (table macro-aliases-table 'mac 'fn) ; or (add-macro-alias mac fn)

 (defun fn (x) x)
 (in-theory (disable mac))

 ;;;;;;;;;;
 ;;; Example 3: ERROR.
 ;;;;;;;;;;

 (defun fn (x) x)
 (defmacro mac1 (x) (fn x))
 (defmacro mac2 (x) (list 'mac1 x))

 ; BAD, since the table event above anticipates fn to be defined as
 ; a function, not a macro (but, no error yet) -- but not (yet) an error:
 (table macro-aliases-table 'mac2 'mac1) ; or (add-macro-alias mac2 mac1)

 ; ERROR, since mac2 does not designate rules, because it aliases a macro:
 (in-theory (disable mac2))

 ; OK, but too late to help with that in-theory event; see below:
 (table macro-aliases-table 'mac1 'fn) ; or (add-macro-alias mac1 fn)

 ; ERROR, since mac2 is still associated with mac1, not with fn:
 (in-theory (disable mac2))

 ;;;;;;;;;;
 ;;; Example 4: Fixed version of Example 3.
 ;;;;;;;;;;

 (defun fn (x) x)
 (defmacro mac1 (x) (fn x))
 (defmacro mac2 (x) (list 'mac1 x))
 (add-macro-alias mac1 fn); or (table macro-aliases-table 'mac1 'fn)

 ; The following is equivalent to (add-macro-alias mac2 fn), since
 ; mac1 is a macro-alias for fn by virtue of the preceding event.
 (add-macro-alias mac2 mac1)

 ; Success:
 (in-theory (disable mac2))
 })")

(defxdoc macro-args
  :parents (macros)
  :short "The formals list of a macro definition"
  :long "@({
  Examples:
  (x y z)
  (x y z &optional max (base '10 basep))
  (x y &rest rst)
  (x y &key max base)
  (&whole sexpr x y)
 })

 <p>The ``lambda-list'' of a macro definition may include simple formal
 parameter names as well as appropriate uses of the following lambda-list
 keywords from Common Lisp, respecting the order shown:</p>

 <ul>

 <li>@('&whole x')<br/>
 @('X') does not represent an actual parameter; rather, it is bound to the
 entire macro call.
 </li>

 <li>@('&optional x1 x2 ...')<br/>
 The actual for any @('xi') may be omitted, in which case the actual for every
 @('xj') with @('j > i') must also be omitted.
 </li>

 <li>@('&rest x')<br/>
 @('X') does not represent an actual parameter; rather, it is bound to the list
 of all actuals provided from that position onward.
 </li>

 <li>@('&body x')<br/>
 This is identical to @('&rest x').
 </li>

 <li>@('&key x')<br/>
 The call may have a keyword argument for @('x') by including @(':x val') after
 all required actual parameters, in which case the formal @('x') is bound to
 the actual @('val').
 </li>

 <li>@('&allow-other-keys')<br/>
 Keyword arguments not specified by @('&key') are allowed but ignored.
 </li>

 </ul>

 <p>ACL2 does not support the Common Lisp lambda-list keywords @('&aux') and
 @('&environment').  In addition, there are the following restrictions:</p>

 <blockquote>

 <p>(1) initialization forms in @('&optional') and @('&key') specifiers must be
 quoted values;</p>

 <p>(2) @('&allow-other-keys') may only be used once, as the last specifier;
 and</p>

 <p>(3) destructuring is not allowed.</p>

 </blockquote>

 <p>The use of default values is allowed, so that an optional or keyword
 argument may be given in any of the following forms.</p>

 <ul>

 <li>@('arg') or, equivalently, @('(arg)')</li>

 <li>@('(arg 'init)')</li>

 <li>@('(arg 'init supplied-p)')</li>

 </ul>

 <p>For the second and third forms above, @('init') is the value when the
 argument is not supplied; for the first form, that default value is @('nil').
 Note that it must be quoted.  The @('supplied-p') argument is @('nil') when
 the argument is not supplied, else is @('t'), as illustrated by the demo
 below.</p>

 <p>You are encouraged to experiment with the macro facility.  One way to do so
 is to define a macro that does nothing but return the quotation of its
 arguments, e.g.,</p>

 @({
  (defmacro demo (x y &optional (opt '5) &key (key1 '6 key1p) key2)
    (list 'quote (list x y opt key1 key1p key2)))
 })

 <p>You may then execute the macro on some sample forms, e.g.,</p>

 @({
    term                         value
  (demo 1 2)                (1 2 5 6 NIL NIL)
  (demo 1 2 3)              (1 2 3 6 NIL NIL)
  (demo 1 2 3 :key1 6)      (1 2 3 6 T NIL)
  (demo 1 2 3 :key1 7)      (1 2 3 7 T NIL)
  (demo 1 2 3 :key2 8)      (1 2 3 6 NIL 8)
  (demo 1 2 :key1 3)        error:  non-even key/value arglist
                            (because :key1 is used as opt)
 })

 <p>In particular, Common Lisp specifies (hence so does ACL2) that if you use
 both @('&rest') and @('&key'), then both will be bound using the same list of
 arguments.  The following example should serve to illustrate how this
 works.</p>

 @({
  ACL2 !>(defmacro foo (&rest args &key k1 k2 k3)
           (list 'quote (list args k1 k2 k3)))

  Summary
  Form:  ( DEFMACRO FOO ...)
  Rules: NIL
  Warnings:  None
  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
   FOO
  ACL2 !>(foo :k1 3 :k2 4 :k3 5)
  ((:K1 3 :K2 4 :K3 5) 3 4 5)
  ACL2 !>(foo :k1 3 :k2 4)
  ((:K1 3 :K2 4) 3 4 NIL)
  ACL2 !>(foo :k1 3 :bad-key 7)

  ACL2 Error in macro expansion:  Illegal key/value args (:BAD-KEY 7)
  in macro expansion of (FOO :K1 3 :BAD-KEY 7).  The argument list for
  FOO is
  (&REST ARGS &KEY K1 K2 K3).

  ACL2 !>
 })

 <p>If we don't want to get the error above, we can use @('&allow-other-keys'),
 as follows.</p>

 @({
  ACL2 !>(defmacro bar (&rest args &key k1 k2 k3
                              &allow-other-keys)
           (list 'quote (list args k1 k2 k3)))

  Summary
  Form:  ( DEFMACRO BAR ...)
  Rules: NIL
  Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
   BAR
  ACL2 !>(bar :k1 3 :bad-key 7)
  ((:K1 3 :BAD-KEY 7) 3 NIL NIL)
  ACL2 !>
 })

 <p>Also see @(see trans).</p>")

(defxdoc macro-command
  :parents (proof-builder)
  :short "Compound command for the interactive proof-builder"
  :long "<p>The interactive @(see proof-builder) supports the definition of
 compound commands, called ``macro commands'', which expand into zero or more
 other commands.  Some of these are ``atomic'' macro commands; these are viewed
 as a single command step when completed successfully.</p>

 <p>More @(see documentation) may be written on the interactive @(see
 proof-builder).  For now, we simply point out that there are lots of examples
 of the use of @('define-pc-macro') and @('define-pc-atomic-macro') in the ACL2
 source file @('"proof-builder-b.lisp"').  The former is used to create macro
 commands, which can be submitted to the interactive loop (see @(see verify))
 and will ``expand'' into zero or more commands.  The latter is similar, except
 that the undoing mechanism (see @(see acl2-pc::undo)) understands atomic macro
 commands to represent single interactive commands.  Also see @(see
 acl2-pc::comm) and see @(see acl2-pc::commands) for a discussion of the
 display of interactive commands.</p>

 <p>Also see @(see toggle-pc-macro) for how to change a macro command to an
 atomic macro command, and vice versa.</p>")

(defxdoc macrolet
  :parents (basics acl2-built-ins)
  :short "Local binding of macro symbols"
  :long "<p>See @(see flet) for an analogous utility for defining functions
 locally.</p>

 @({
 Example Form:
 (defun f1 (x)
   (macrolet ((mac (a) (list 'quote a)))
     (cons x (mac x))))
 })

 <p>The Example Form above is equivalent to the following, in which the call of
 local macro @('mac') has been expanded.</p>

 @({
 (defun f1-alt (x)
   (cons x (quote x)))
 })

 <p>The General Forms are similar to those of @(tsee flet).</p>

 @({
 General Forms:
 (macrolet (def1 ... defk) body)
 (macrolet (def1 ... defk) declare-form1 .. declare-formk body)
 })

 <p>where @('body') is a term, and each @('defi') is a definition as in @(tsee
 defmacro) but with the leading @('defmacro') symbol omitted.  See @(see
 defmacro), but see @(see declare) for the declarations permitted directly
 under the @('defi').  On the other hand, regarding the @('declare-formi') (if
 any are supplied): 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').  Unlike the
 related utility @(tsee flet), those @('inline') and @('notinline')
 declarations are unlikely to have any effect.</p>

 <p>The innermost @(tsee flet) or @('macrolet') binding of a symbol, @('f'),
 above a call of @('f'), is the one that provides the definition of @('f') for
 that call.  Note that neither @('flet') nor @('macrolet') provide recursion:
 that is, the definition of @('f') in an @('flet') or @('macrolet') binding of
 @('f') is ignored in the body of that binding.</p>

 <p>The following requirements are imposed by Common Lisp and enforced by
 ACL2.</p>

 <ul>

 <li>Every variable occurring in the body of a @('defi') must be a formal
 parameter name of that @('defi').</li>

 <li>No function or macro symbol called in the body of a @('defi') may be
 defined by a superior @('flet') or @('macrolet') binding.  (Not every Common
 Lisp implementation includes this restriction for superior @('macrolet')
 bindings, but at least one (GCL) does so we include it in ACL2.)</li>

 </ul>

 <p>Although @('macrolet') behaves in ACL2 essentially as it does in Common
 Lisp, ACL2 imposes the following restrictions and qualifications.</p>

 <ul>

 <li>Every @(tsee declare) form for a local definition (@('def1')
 through @('defk'), above) must be an @('ignore'), @('ignorable'), or @('type')
 expression.</li>

 <li>Each @('defi') must bind a different symbol.</li>

 <li>Each @('defi') must bind a symbol that is a legal name for an ACL2 macro.
 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.</li>

 <li>When an expression @('(macrolet (... defi ...) ...)') occurs in the body
 of a @('DO') @(tsee loop$) expression, nevertheless constructs such as
 @('PROGN') and @('SETQ') that ACL2 permits in @('DO') @('loop$') bodies are
 not permitted in @('defi') (unless they occur within the scope of a @('DO')
 @('loop$') expression in that body).</li>

 </ul>

 <p>@('Macrolet') bindings are evaluated in parallel.  Consider the following
 example.</p>

 @({
 (defun f1 (x) (cons x 'x))
 (macrolet ((f1 (x) x)
            (f2 () (list 'quote
 ; The following reference is to the global f1,
 ; not to the identity macro just above.
                         (f1 3))))
   (f2))
 })

 <p>The @('macrolet') form above evaluates to @('(3 . x)'), not to 3, as
 explained in the comment above.  Here is a somewhat analogous form that one
 might expect to evaluate to 3, but that is not the case; see below.</p>

 @({
 (macrolet ((f1 (x) x))
   (macrolet ((f2 () (list 'quote (f1 3))))
     (f2)))
 })

 <p>The body of @('f2') calls a symbol, @('f1'), that is bound by a superior
 @('macrolet') binding.  As noted above, this is illegal (also for superior
 @('flet') bindings).</p>

 <p>Under the hood, ACL2 expands away @('macrolet') bindings.  The following
 example illustrates this point.</p>

 @({
 ACL2 !>:trans (macrolet ((mac (a) (list 'cons a a)))
                 (car (mac b)))

 (CAR (CONS B B))

 => *

 ACL2 !>
 })

 <p>@('Macrolet') is part of Common Lisp.  See any Common Lisp documentation
 for more information.  We conclude by pointing out an important aspect of
 @('macrolet') shared by ACL2 and Common Lisp: The binding is lexical, not
 dynamic.  That is, the @('macrolet') binding of a symbol only applies to calls
 of that symbol in the body of the @('macrolet'), not other calls made in the
 course of evaluation.  See @(see flet) for discussion of this point.</p>")

(defxdoc macros
  :parents (acl2)
  :short "Macros allow you to extend the syntax of ACL2.")

(defxdoc magic-ev-fncall
  :parents (meta)
  :short "Call the named function on the given arguments and return the value."
  :long "<p>Introduction.  @('Magic-ev-fncall') is a @(see logic)-mode function
 that can apply a given function (which need not be in logic mode) to an
 argument list.  Although the result can be computed, @('magic-ev-fncall') is
 technically a constrained function (with unknown constraints), which can be
 assumed in metafunctions and @(see clause) processors to produce correct
 results, via @(see meta-extract).</p>

 <p>Examples:</p>

 @({
  (magic-ev-fncall 'cons '(3 4) state t nil)
    = (mv nil '(3 . 4))
  (magic-ev-fncall (car '(floor foo)) (list (+ 6 7) 5) state t nil)
    = (mv nil 2)
 })

 <p>General Form:</p>

 @({
  (magic-ev-fncall fn arglist state hard-error-returns-nilp aokp)
 })

 <p>where @('fn') is a function symbol, @('arglist') is a suitable argument
 list for @('fn'), and the last two formals are described below.  When
 successful, the result is @('(mv nil value)') where @('value') is the
 application of @('fn') to @('arglist').  Although this fact cannot be proven,
 it may be assumed correct in metafunctions and clause processors via @(see
 meta-extract), assuming of course that @('fn') is a @(see logic)-mode
 function.</p>

 <p>In general, the result is either @('(mv t error-msg)') (if, e.g., the
 function was not defined, the arity was wrong, or the guards were violated) or
 @('(mv nil value)') on success.  In the case of a @(see multiple-value)d
 function the second return value is the list of values.  A non-nil error
 message, @('error-msg'), is a message suitable for printing with @(tsee fmt);
 see @(see msg).</p>

 <p>If a hard error is encountered during execution and
 @('hard-error-returns-nilp') is non-@('nil'), then the error is ignored and
 the value returned is @('(mv nil nil)') (note that the logical value of a call
 of @('HARD-ERROR') is @('nil')).  If @('hard-error-returns-nilp') is @('nil')
 then the return value is of the form @('(mv T error-msg)').</p>

 <p>The @('aokp') argument controls whether attachments to constrained
 functions may be executed (see @(see defattach)).  If @('nil'), then an error
 message is returned when an attachment would otherwise be executed.</p>

 <p>When used in a clause-processor or metafunction, it can be assumed via a
 @(see meta-extract) hypothesis that @('magic-ev-fncall') works correctly with
 respect to the evaluator, but only if @('hard-error-returns-nilp') is @('t')
 and @('aokp') is @('nil').</p>

 <p>The @(see guard) for @('(magic-ev-fncall fn arglist state h aokp)') is
 @('t'), but evaluation of this call enforces the following requirements.</p>

 <ul>

 <li>@('Fn') must be a function symbol of the current ACL2 @(see world) other
 than @('if'), whose arity is equal to the length of the true-list,
 @('arglist').</li>

 <li>@('Fn') must not have any @('stobj') inputs or be a stobj creator.</li>

 <li>Calls of @('fn') must not require a trust tag (see @(see defttag)).</li>

 <li>@('Fn') must not be untouchable (see @(see push-untouchable)).</li>

 </ul>

 <p>The implementation of these checks incorporates a bit of trickery so that
 they are reasonably efficient.</p>

 <p>Note that @(tsee set-guard-checking) affects evaluation of calls of
 @('(magic-ev-fncall fn ...)') just as it affects calls of @('fn'), for example
 as follows.</p>

 @({
 ACL2 !>(magic-ev-fncall 'car '((a b c)) state t nil)
 (NIL A)
 ACL2 !>(magic-ev-fncall 'car '(3) state t nil)
 (T <... message elided here ...>)
 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 >(magic-ev-fncall 'car '(3) state t nil)
 (NIL NIL)
 ACL2 >
 })

 <p>Additional Notes.</p>

 <ul>

 <li>If @('fn') is a @(see program)-mode function, then the call will be
 evaluated under @(see safe-mode), which avoids raw Lisp errors due to calls of
 ill-@(see guard)ed program-mode functions.</li>

 <li>If the application of @('fn') returns multiple values @('(mv v1 v2 ...)'),
 then the resulting value will be the corresponding list @('(v1 v2 ...)').</li>

 <li>A reasonable model for @('(magic-ev-fncall 'fn (list a1 a2 ...) state h
 aokp)') is @('(ec-call (fn a1 a2 ...))').</li>

 </ul>")

(defxdoc mailing-lists
  :parents (acl2 about-acl2 community)
  :short "Mailing lists for ACL2 users"
  :long "<p>There are the following mailing lists for ACL2 users.  You can
 post messages to these lists only if you are a member, but anyone can view the
 archives.

 <ul>
 <li><b>acl2 list</b>: General ACL2 list for users and others interested in ACL2
   <ul>
     <li>To post: <tt><a href='mailto:acl2@utlists.utexas.edu'>acl2@utlists.utexas.edu</a></tt></li>
     <li>To subscribe, unsubscribe, or view archives:
       <tt><a href='https://utlists.utexas.edu/sympa/info/acl2'>https://utlists.utexas.edu/sympa/info/acl2</a></tt></li>
   </ul>
 </li>

 <li><b>acl2-help list</b>: ACL2 help list, for questions about using
   ACL2 <font color='red'>(recommended for new users)</font>
   <ul>
     <li>To post: <tt><a href='mailto:acl2-help@utlists.utexas.edu'>acl2-help@utlists.utexas.edu</a></tt></li>
     <li>To subscribe, unsubscribe, or view archives:
       <tt><a href='https://utlists.utexas.edu/sympa/info/acl2-help'>https://utlists.utexas.edu/sympa/info/acl2-help</a></tt></li>
   </ul>
 </li>

 <li><b>acl2-books list</b>: Mailing list for discussion of
 cutting-edge developments in ACL2 and the ACL2 Community Books
   <ul>
     <li>To post: <tt><a
 href='mailto:acl2-books@googlegroups.com'>acl2-books@googlegroups.com</a></tt></li>
     <li>To subscribe, unsubscribe, or view archives:
       <tt><a href='https://groups.google.com/forum/#!forum/acl2-books'>https://groups.google.com/forum/#!forum/acl2-books</a></tt></li>
   </ul>
 </li>

 </ul></p>

 <p>Finally, please report bugs in ACL2 to
 <a href='mailto:kaufmann@cs.utexas.edu'>Matt Kaufmann</a>.</p>

 <p>See @(see community) for ways to connect with other ACL2 users,
 get help with ACL2, and contribute to improving ACL2 and its
 @(see community-books).</p>
 ")

(defxdoc make
  :parents (defrec acl2-built-ins)
  :short "Constructor macro for @(see defrec) structures."
  :long "<p>The @('make') macro is built into ACL2, and allows you to construct
 new instances of structures that have been introduced with @(see defrec).  For
 instance:</p>

 @({
    (make employee :name "Jimmy"
                   :salary 0
                   :position "Unpaid Intern")
 })

 <p>Creates a new @('employee') structure with the given values for its
 @('name'), @('salary'), and @('position') fields.  See @(see defrec) for more
 information.</p>")

(defxdoc make-character-list
  :parents (characters acl2-built-ins)
  :short "@(see coerce) to a list of characters"
  :long "<p>Non-characters in the given list are @(see coerce)d to the
 character with code 0.</p>

 @(def make-character-list)")

(defxdoc make-event
  :parents (events macros)
  :short "Evaluate (expand) a given form and then evaluate the result"
  :long "<p>@('Make-event') is a utility for generating @(see events).  It
 provides a capability not offered by Lisp macros (see @(see defmacro)), as it
 allows access to the ACL2 @(see state) and logical @(see world).  In essence,
 the expression @('(make-event form)') replaces itself with the result of
 evaluating @('form') &mdash; let's call that result @('ev') &mdash; as though
 one had submitted @('ev') instead of the @('make-event') call.  For example,
 @('(make-event (quote (defun f (x) x)))') is equivalent to the event @('(defun
 f (x) x)').</p>

 <p>We assume basic familiarity with the ACL2 <i>state</i>.  For relevant
 background, see @(see state) and perhaps see @(see
 programming-with-state).</p>

 <p>There are several simple examples below.  For examples that can give
 additional insight into the use of @('make-event') for tool development, see
 @(see make-event-example-1) and @(see make-event-example-2).  Also see the
 @('make-event/') subdirectory of the ACL2 @(see community-books) for more
 examples, for example, @('books/make-event/search-generation.lisp').</p>

 <p>We break this documentation into the following sections.</p>

 <ul>

 <li><b>Introduction</b></li>

 <li><b>Detailed Documentation</b></li>

 <li><b>Error Reporting</b></li>

 <li><b>Restriction to Event Contexts</b></li>

 <li><b>Examples Illustrating How to Access State</b></li>

 <li><b>Advanced Expansion Control</b></li>

 </ul>

 <p>We begin with an introduction, which focuses on examples and introduces the
 key notion of ``expansion phase''.</p>

 <h3>Introduction</h3>

 <p>@('Make-event') is particularly useful for those who program using the ACL2
 @(tsee state); see @(see programming-with-state).  That is because the
 evaluation of @('form') may read and even modify the ACL2 @(tsee state).</p>

 <p>Suppose for example that we want to define a constant @('*world-length*'),
 that is the length of the current ACL2 @(see world).  A @('make-event') form
 can accomplish this task, as follows.</p>

 @({
    ACL2 !>(length (w state))
    98883
    ACL2 !>(make-event
            (list 'defconst '*world-length* (length (w state))))

    Summary
    Form:  ( DEFCONST *WORLD-LENGTH* ...)
    Rules: NIL
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)

    Summary
    Form:  ( MAKE-EVENT (LIST ...))
    Rules: NIL
    Time:  0.01 seconds (prove: 0.00, print: 0.00, other: 0.01)
     *WORLD-LENGTH*
    ACL2 !>*world-length*
    98883
    ACL2 !>(length (w state))
    98890
    ACL2 !>
 })

 <p>How did this work?  First, evaluation of the form @('(list 'defconst
 '*world-length* (length (w state)))') returned the event form @('(defconst
 *world-length* 98883)').  Then that event form was automatically submitted to
 ACL2.  Of course, that changed the ACL2 logical @(see world), which is why the
 final value of @('(length (w state))') is greater than its initial value.</p>

 <p>The example above illustrates how the evaluation of a @('make-event') call
 takes place in two phases.  The first phase evaluates the argument of the
 call, in this case @('(list 'defconst '*world-length* (length (w state)))'),
 to compute an event form, in this case @('(defconst *world-length* 98883)').
 We call this evaluation the ``expansion'' phase.  Then the resulting event
 form is evaluated, which in this case defines the constant
 @('*world-length*').</p>

 <p>Now suppose we would like to introduce such a @(tsee defconst) form any
 time we like.  It is common practice to define macros to automate such tasks.
 Now we might be tempted simply to make the following definition.</p>

 @({
  ; WRONG!
  (defmacro define-world-length-constant (name state)
    (list 'defconst name (length (w state))))
 })

 <p>But ACL2 rejects such a definition, because the formal parameter
 @('"STATE"') is bound to the syntactic object in the macro call, not to the
 actual ACL2 @(see state); see @(see defmacro).  You can try to experiment with
 other such direct methods to define a macro that accesses the ACL2 state, but
 they won't work.</p>

 <p>Instead, however, you can use the approach illustrated by the
 @('make-event') example above to define the desired macro, as follows.</p>

 @({
  (defmacro define-world-length-constant (name)
    `(make-event (list 'defconst ',name (length (w state)))))
 })

 <p>Here is a log that may help to explain this macro, assuming it has been
 defined as displayed just above.</p>

 @({
 ACL2 !>:trans1 (define-world-length-constant *foo*)
  (MAKE-EVENT (LIST 'DEFCONST
                    '*FOO*
                    (LENGTH (W STATE))))
 ACL2 !>(LIST 'DEFCONST
              '*FOO*
              (LENGTH (W STATE)))
 (DEFCONST *FOO* 109707)
 ACL2 !>
 ACL2 !>(define-world-length-constant *foo*)

 Summary
 Form:  ( DEFCONST *FOO* ...)
 Rules: NIL
 Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)

 Summary
 Form:  ( MAKE-EVENT (LIST ...))
 Rules: NIL
 Time:  0.01 seconds (prove: 0.00, print: 0.00, other: 0.01)
  *FOO*
 ACL2 !>*foo*
 109707
 ACL2 !>:pe *foo*
            2:x(DEFINE-WORLD-LENGTH-CONSTANT *FOO*)
               
 >              (DEFCONST *FOO* 109707)
 ACL2 !>(length (w state))
 109713
 ACL2 !>(define-world-length-constant *bar*)

 Summary
 Form:  ( DEFCONST *BAR* ...)
 Rules: NIL
 Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)

 Summary
 Form:  ( MAKE-EVENT (LIST ...))
 Rules: NIL
 Time:  0.01 seconds (prove: 0.00, print: 0.00, other: 0.01)
  *BAR*
 ACL2 !>*bar*
 109713
 ACL2 !>:pe *bar*
            3:x(DEFINE-WORLD-LENGTH-CONSTANT *BAR*)
               
 >              (DEFCONST *BAR* 109713)
 ACL2 !>(length (w state))
 109719
 ACL2 !>
 })

 <p>The expansion phase can be used for computation that has side effects,
 generally by modifying state.  Here is a modification of the above example
 that does not change the ACL2 world at all, but instead saves the length of the
 world into a state global variable (see @(see assign)).</p>

 @({
  (make-event
   (er-progn (assign my-world-length (length (w state)))
             (value '(value-triple nil))))
 })

 <p>Notice that this time, the value returned by the expansion phase is not a
 single value; rather, it is an @(see error-triple) whose value component is an
 event form, namely, the event form @('(value-triple nil)').  Evaluation of
 that event form does not change the ACL2 world (see @(see value-triple)).
 Thus, the sole purpose of the @('make-event') call above is to change the
 @(see state) by associating the length of the current logical world with the
 state global, @('my-world-length').  After evaluating this form, @('(@
 my-world-length)') provides the length of the ACL2 world, as illustrated by
 the following transcript.</p>

 @({
 ACL2 !>:pbt 0
            0:x(EXIT-BOOT-STRAP-MODE)
 ACL2 !>(length (w state))
 109700
 ACL2 !>(make-event
             (er-progn (assign my-world-length (length (w state)))
                       (value '(value-triple nil))))

 Summary
 Form:  ( MAKE-EVENT (ER-PROGN ...))
 Rules: NIL
 Time:  0.01 seconds (prove: 0.00, print: 0.00, other: 0.01)
  NIL
 ACL2 !>(length (w state))
 109700
 ACL2 !>:pbt 0
            0:x(EXIT-BOOT-STRAP-MODE)
 ACL2 !>
 })

 <p>When @('make-event') is invoked by a book, it is expanded during book
 certification but not, by default, when the book is included.  Consider again
 the example @('(define-world-length-constant *foo*)') given above.  If that
 form is in a book, then the value of @('*foo*') will be the length of the
 world at the time this form was invoked during book certification, regardless
 of world length at @(tsee include-book) time.  That is because the expansion,
 @('(DEFCONST *FOO* 109700)'), is recorded in the book's @(see certificate) and
 re-used during a subsequent @(tsee include-book).</p>

 <p>However, the keyword @(':check-expansion') may be given the value @('t') so
 that the expansion is done even during @('include-book'), which comes with a
 check that the result is the same as it was during book certification.  This
 keyword can be useful for side effects.  For example, if you insert the
 following form in a book, then the length of the world will be printed when
 the form is encountered, whether during @(tsee certify-book) or during @(tsee
 include-book).</p>

 @({
  (make-event
   (pprogn (fms "Length of current world: ~x0~|"
                (list (cons #\0 (length (w state))))
                *standard-co* state nil)
           (value '(value-triple nil)))
   :check-expansion t)
 })

 <h3>Detailed Documentation</h3>

 @({
  Examples:

  ; Trivial example: evaluate (quote (defun foo (x) x)) to obtain
  ; (defun foo (x) x), which is then evaluated.
  (make-event (quote (defun foo (x) x)))

  ; Evaluate (generate-form state) to obtain (mv nil val state), and
  ; then evaluate val.  (Generate-form is not specified here, but
  ; imagine for example that it explores the state and then generates
  ; some desired definition or theorem.)
  (make-event (generate-form state))

  ; As above, but make sure that if this form is in a book, then when
  ; we include the book, the evaluation of (generate-form state)
  ; should return the same value as it did when the book was
  ; certified.
  (make-event (generate-form state)
              :CHECK-EXPANSION t)

  General Form:
  (make-event form
              :CHECK-EXPANSION chk
              :ON-BEHALF-OF obj
              :EXPANSION? form
              :SAVE-EVENT-DATA save)
 })

 <p>where @('chk') is @('nil') (the default), @('t'), or the intended
 ``expansion result'' from the evaluation of @('form') (as explained below);
 @('obj') is an arbitrary ACL2 object, used only in reporting errors in
 expansion, i.e., in the evaluation of form; and @('save') is arbitrary but is
 considered only as either @('nil') or non-@('nil').  The @(':EXPANSION?')
 keyword is discussed in the final section, on Advanced Expansion Control.  See
 @(see make-event-details) for discussion of the @(':ON-BEHALF-OF')
 and :SAVE-EVENT-DATA keywords.</p>

 <p>We strongly recommend that you browse some @('.lisp') files in the
 community books directory @('books/make-event/').  You may even find it
 helpful, in order to understand @('make-event'), to do so before continuing to
 read this documentation.  You may also find it useful to browse community book
 @('books/std/testing/eval.lisp'), which contains definitions of macros
 @('must-succeed') and @('must-fail') that are useful for testing and are used
 in many books in the @('books/make-event/') directory, especially
 @('eval-tests.lisp').  Another example, @('books/make-event/defrule.lisp'),
 shows how to use macros whose calls expand to @('make-event') forms, which in
 turn can generate @(see events).  For more examples, see file
 @('books/make-event/Readme.lsp').  Other than the examples, the explanations
 here should suffice for most users.  If you want explanations of subtler
 details, see @(see make-event-details).</p>

 <p>Note that @('make-event') is generally legal only where an embedded event
 form is expected: essentially, at the top level of a book or the
 read-eval-print loop, possibly within surrounding calls of @('make-event') or
 of event constructors such as @(tsee progn) and @(tsee encapsulate).  For
 details see the section ``Restriction to Event Contexts'', below.</p>

 <p>@('Make-event') is related to Lisp macroexpansion in the sense that its
 argument is evaluated to obtain an expansion result, which is evaluated again.
 Let us elaborate on each of these notions in turn: ``is evaluated,''
 ``expansion result'', and ``evaluated again.''  The final section, on Advanced
 Expansion Control, will generalize these processes in a way that we ignore for
 now.</p>

 <blockquote>

 <p>``is evaluated'' &mdash; The argument can be any expression, which is
 evaluated as would be any expression submitted to ACL2's top level loop.
 Thus, @(tsee state) and user-defined @(tsee stobj)s may appear in the form
 supplied to @('make-event').  Henceforth, we will refer to this evaluation as
 ``expansion.''  Expansion is actually done in a way that restores ACL2's
 built-in @(tsee state) global variables, including the logical @(see world),
 to their pre-expansion values (with a few exceptions &mdash; see @(see
 make-event-details) &mdash; and where we note that changes to user-defined
 @(tsee state) global variables (see @(see assign)) are preserved).  So, for
 example, events might be evaluated during expansion, but they will disappear
 from the logical @(see world) after expansion returns its result.  Moreover,
 proofs are enabled by default during expansion (see @(see ld-skip-proofsp)) if
 keyword @(':CHECK-EXPANSION') is supplied a non-@('nil') value or a certain
 attachment is made (see (4) below).</p>

 <p>``expansion result'' &mdash; The above expansion may result in an ordinary
 (non-@(tsee state), non-@(tsee stobj)) value, which we call the ``expansion
 result.''  Or, expansion may result in a multiple value of the form @('(mv erp
 val state)'), or, more generally, @('(mv erp val state stobj-1 ... stobj-k)')
 where each @('stobj-i') is a @(see stobj); then the expansion result is
 @('val') unless @('erp') is not @('nil'), in which case there is no expansion
 result, and the original @('make-event') evaluates to a soft error.  In either
 case (single or multiple value), either @('val') is an embedded event form
 (see @(see embedded-event-form)), or else the original @('make-event')
 evaluates to a soft error, printed as described under ``Error Reporting''
 below.<br/>
 (<i>Technical remark</i>: The expansion result described above may be modified
 for @(tsee include-book), @(tsee add-include-book-dir), and @(tsee
 add-include-book-dir!), replacing @(see book-name)s to indicate @(see
 full-book-name)s.  For further details see comments in source function
 @('make-include-books-absolute').  End of technical remark.)</p>

 <p>``evaluated again'' &mdash; the expansion result is evaluated in place of
 the original @('make-event').</p>

 </blockquote>

 <p>The expansion process can invoke subsidiary calls of @('make-event'), and
 the expansion result can (perhaps after macroexpansion) be a call of
 @('make-event').  It can be useful to track all these @('make-event') calls.
 The @(see state) global variable @('make-event-debug') may be set to a
 non-@('nil') value, for example @('(assign make-event-debug t)'), in order to
 see a trace of the expansion process, where a level is displayed (as in
 ``@('3>')'') to indicate the depth of subsidiary expansions.</p>

 <p>Expansion of a @('make-event') call will yield an event that replaces the
 original @('make-event') call.  In particular, if you put a @('make-event')
 form in a book, then in essence it is replaced by its expansion result,
 created during the proof pass of the @(tsee certify-book) process.  We now
 elaborate on this idea of keeping the original expansion.</p>

 <p>A @('make-event') call generates a ``@('make-event') replacement'' that may
 be stored by the system.  In the simplest case, this replacement is the
 expansion result.  When a book is certified, these replacements are stored in
 a book's certificate (technically, in the @(':EXPANSION-ALIST') field).  Thus,
 although the book is not textually altered during certification, one may
 imagine a ``book expansion'' corresponding to the original book, in which
 events are substituted by replacements that were generated during the proof
 phase of certification.  A subsequent @(tsee include-book) will then include
 the book expansion corresponding to the indicated book.  When a book is
 compiled during @(tsee certify-book), it is actually the corresponding book
 expansion, stored as a temporary file, that is compiled instead.  That
 temporary file is deleted after compilation unless one first evaluates the
 form @('(assign keep-tmp-files t)').  Note however that all of the original
 forms must still be legal @(see events); see @(see embedded-event-form).  So
 for example, if the first event in a book is @('(local (defmacro my-id (x)
 x))'), and is followed by @('(my-id (make-event ...))'), the final
 ``@('include-book')'' pass of @(tsee certify-book) will fail because
 @('my-id') is not defined when the @('my-id') call is encountered.</p>

 <p>A @('make-event') replacement might not be the expansion when either of the
 keyword arguments @(':CHECK-EXPANSION') or @(':EXPANSION?') is supplied.  We
 deal with the latter in the final section, on Advanced Expansion Control.  If
 @(':CHECK-EXPANSION t') is supplied and the expansion is @('exp'), then the
 replacement is obtained from the original @('make-event') call, by
 substituting @('exp') for @('t') as the value of keyword
 @(':CHECK-EXPANSION').  Such a @('make-event') call &mdash; during the second
 pass of an @(tsee encapsulate), or during event processing on behalf of @(tsee
 include-book) other than when including a book near the end of its
 certification process &mdash; will do the expansion again and check that the
 expansion result is equal to the original expansion result, @('exp').  In the
 unusual case that you know the expected expansion result, @('res'), you can
 specify @(':CHECK-EXPANSION res') in the first place, so that the check is
 also done during the initial evaluation of the @('make-event') form.
 IMPORTANT BUT OBSCURE DETAIL: That expansion check is only done when
 processing events, not during a preliminary load of a book's compiled file.
 The following paragraph elaborates.</p>

 <p>(Here are details on the point made just above, for those who use the
 @(':CHECK-EXPANSION') argument to perform side-effects on the @(see state).
 When you include a book, ACL2 generally loads a compiled file before
 processing the events in the book; see @(see book-compiled-file).  While it is
 true that a non-@('nil') @(':CHECK-EXPANSION') argument causes @(tsee
 include-book) to perform expansion of the @('make-event') form during event
 processing it does <i>not</i> perform expansion when the compiled file (or
 expansion file; again, see @(see book-compiled-file)) is loaded.)</p>

 <p>ACL2 performs the following space-saving optimization: when the expansion
 result is a @(tsee local) event, then the @('make-event') replacement is
 @('(local (value-triple :ELIDED))').</p>

 <p>The notion of ``expansion'' and ``replacement'' extend to the case that a
 call of @('make-event') is found in the course of macroexpansion.  The
 following example illustrates this point.</p>

 @({
  (encapsulate
   ()
   (defmacro my-mac ()
     '(make-event '(defun foo (x) x)))
   (my-mac))
  :pe :here
 })

 <p>The above call of @(tsee pe) shows that the form @('(my-mac)') has a
 @('make-event') expansion (and replacement) of @('(DEFUN FOO (X) X)'):</p>

 @({
  (ENCAPSULATE NIL
               (DEFMACRO MY-MAC
                         NIL
                         '(MAKE-EVENT '(DEFUN FOO (X) X)))
               (DEFUN FOO (X) X))
 })

 <h3>Error Reporting</h3>

 <p>Suppose that expansion produces a soft error as described above.  That is,
 suppose that the argument of a @('make-event') call evaluates to a multiple
 value @('(mv erp val state ...)') where @('erp') is not @('nil').  If @('erp')
 is a string, then that string is printed in the error message.  If @('erp') is
 a @(tsee cons) pair whose @(tsee car) is a string, then the error prints
 @('"~@0"') with @('#\0') bound to that @('cons') pair; see @(see fmt).  Any
 other non-@('nil') value of @('erp') causes a generic error message to be
 printed.</p>

 <h3>Restriction to Event Contexts</h3>

 <p>A @('make-event') call must occur either at the top level, or during
 @('make-event') expansion, or as an argument of an event constructor.  We
 explain in more detail below.  This restriction is imposed to enable ACL2 to
 track expansions produced by @('make-event').</p>

 <p>The following examples illustrate this restriction.</p>

 @({
  ; Legal:
  (progn (with-output
          :on summary
          (make-event '(defun foo (x) x))))

  ; Illegal:
  (mv-let (erp val state)
          (make-event '(defun foo (x) x))
          (mv erp val state))
 })

 <p>More precisely: a @('make-event') call that is not itself evaluated during
 @('make-event') expansion is subject to the following requirement.  After
 macroexpansion has taken place, such a @('make-event') call must be in an
 ``event context'', defined recursively as follows.  (All but the first two
 cases below correspond to similar cases for constructing events; see @(see
 embedded-event-form).)</p>

 <ul>

 <li>A form submitted at the top level, or more generally, supplied to a call
 of @(tsee ld), is in an event context.</li>

 <li>A form occurring at the top level of a book is in an event context.</li>

 <li>If @('(')@(tsee LOCAL)@(' x1)') is in an event context, then so is
 @('x1').</li>

 <li>If @('(')@(tsee SKIP-PROOFS)@(' x1)') is in an event context, then so is
 @('x1').</li>

 <li>If @('(')@(tsee MAKE-EVENT)@(' x ...)') is in an event context and its
 expansion @('x1') is an embedded event form, then @('x1') is in an event
 context.</li>

 <li>If @('(')@(tsee WITH-OUTPUT)@(' ... x1)'), @('(')@(tsee
 WITH-PROVER-STEP-LIMIT)@(' ... x1 ...)'), or @('(')@(tsee
 WITH-PROVER-TIME-LIMIT)@(' ... x1)') is in an event context, then so is
 @('x1').</li>

 <li>For any call of @(tsee PROGN) or @(tsee PROGN!), each of its arguments is
 in an event context.</li>

 <li>For any call of @(tsee ENCAPSULATE), each of its arguments except the
 first (the signature list) is in an event context.</li>

 <li>If @('(RECORD-EXPANSION x1 x2)') is in an event context, then @('x1') and
 @('x2') are in event contexts.  Note: @('record-expansion') is intended for
 use only by the implementation.</li>

 </ul>

 <p>Low-level remark, for system implementors.  There is the one exception to
 the above restriction: a single @(tsee state-global-let*) form immediately
 under a @('progn!') call.  For example:</p>

 @({
  (progn! (state-global-let* <bindings> (make-event ...)))
 })

 <p>However, the following form may be preferable (see @(see progn!)):</p>

 @({
  (progn! :STATE-GLOBAL-BINDINGS <bindings> (make-event ...))
 })

 <p>Also see @(see remove-untouchable) for an interesting use of this
 exception.</p>

 <h3>Avoiding large @('make-event') forms in @(see certificate) files</h3>

 <p>The @(see certificate) file for a book contains expansions of
 @('make-event') forms from the book.  (Those interested may find details about
 this in an Implementation Note about ``The book expansion'' in the
 documentation topic, @(see make-event-details).)  Those expansions can be very
 large if one is not careful.  Consider the difference between the following
 two events.</p>

 @({
 (make-event
  `(defconst *foo* ,(length (w state))))

 (make-event
  `(defconst *foo* (length ',(w state))))

 })

 <p>The first generates an expansion such as @('(defconst *foo* 122700)')
 (where the numeric value depends on the @(see world) in which the
 @('make-event') form is evaluated).  The second, however, generates an
 expansion of the form @('(defconst *foo* (length '<wrld>))'), where @('<wrld')
 is an ACL2 world &mdash; a very large structure.  The @('.cert') file for a
 book containing the second form will therefore contain many megabytes.
 Moreover, with the second form the length of that world will need to be
 computed when the book is included (which may be fast, but could be slow for a
 different such computation).</p>

 <h3>Examples Illustrating How to Access State</h3>

 <p>You can modify the ACL2 @(see state) by doing your state-changing
 computation during the expansion phase, before expansion returns the event
 that is submitted.  Let us look at some examples and then consider a
 restriction for many built-in state globals.</p>

 <p>First consider the following.  Notice that expansion modifies a state
 global, @('my-global'), during @('make-event') expansion (see @(see assign));
 and then, expansion returns a @(tsee defun) event to be evaluated.</p>

 @({
  (make-event
    (er-progn (assign my-global (length (w state)))
              (value '(defun foo (x) (cons x x)))))
 })

 <p>Then we get:</p>

 @({
    ACL2 !>(@ my-global)
    72271
    ACL2 !>:pe foo
     L        1:x(MAKE-EVENT (ER-PROGN # #))

    >L            (DEFUN FOO (X) (CONS X X))
    ACL2 !>
 })

 <p>Here's a slightly fancier example, where the computation affects the @(tsee
 defun).  In a new session, execute:</p>

 @({
  (make-event
    (er-progn (assign my-global (length (w state)))
              (value `(defun foo (x) (cons x ,(@ my-global))))))
 })

 <p>Then:</p>

 @({
    ACL2 !>(@ my-global)
    72271
    ACL2 !>:pe foo
     L        1:x(MAKE-EVENT (ER-PROGN # #))

    >L            (DEFUN FOO (X) (CONS X 72271))
    ACL2 !>
 })

 <p>Because @('make-event') creates @(see event) forms that can go into @(see
 books) and @(tsee encapsulate) events, you can use @('make-event') forms such
 as those above to modify the ACL2 @(see state) using books and
 @('encapsulate') events.  The most common way to do this is for the
 @('make-event') expansion to be a trivial event form such as @('(value-triple
 nil)'), such as the following.</p>

 @({
 (make-event (er-progn (assign my-list-of-10 (make-list 10))
                       (value '(value-triple nil))))
 })

 <p>The desired effect will take place during calls of @(tsee certify-book),
 but it will generally <b>not</b> take place during @(tsee include-book) on a
 certified book because the expansion is evaluated (it is stored in the book's
 @(see certificate) for this purpose), but the expansion is merely
 @('(value-triple nil)').  To ensure that the original @('make-event') call is
 evaluated even when including the book, use @(':check-expansion t'), for
 example as follows.</p>

 @({
 (make-event (er-progn (assign my-list-of-10 (make-list 10))
                       (value '(value-triple nil)))
             :check-expansion t)
 })

 <p>Note that ACL2 @(see table) @(see events) may avoid the need to use @(see
 state) globals.  For example, instead of the example above, consider this
 example in a new session.</p>

 @({
  (make-event
    (let ((world-len (length (w state))))
      `(progn (table my-table :STORED-WORLD-LENGTH ,world-len)
              (defun foo (x) (cons x ,world-len)))))
 })

 <p>Then:</p>

 @({
    ACL2 !>(table my-table)
     ((:STORED-WORLD-LENGTH . 72271))
    ACL2 !>:pe foo
              1:x(MAKE-EVENT (LET # #))

    >L            (DEFUN FOO (X) (CONS X 72271))
    ACL2 !>
 })

 <p>Many built-in @(see state) globals revert after expansion.  If your own
 state global (like @('my-global') above) can be set during expansion, then the
 new value will persist.  But that persistence will fail for many state
 globals, specifically, those that are stored in the list,
 @('*protected-system-state-globals*').  We advise users <b>not</b> to assume
 that system state modifications, such as the state of guard-checking, will
 persist after executing a @('make-event') form; persistence depends on the
 relevant state globals not being in the list,
 @('*protected-system-state-globals*').</p>

 <p>That advice may suffice for most users.  But if you want to understand the
 point above more deeply, then consider the following example.</p>

 @({
 (make-event
  (er-progn (set-guard-checking :none) ; sets state global 'guard-checking-on
            (assign my-global (car 3))
            (value (list 'value-triple (@ my-global)))))
 })

 <p>This @('make-event') form succeeds and afterwards, the value of @('(@
 my-global)') is @('nil'), which of course is the value expected after the call
 above of @(tsee assign).  However, the value of @('(@ guard-checking-on)')
 after executing this @('make-event') form is @('t'), not @(':none').  That is
 because the symbol @('guard-checking-on') belongs to the list of symbols
 stored in the constant, @('*protected-system-state-globals*'), and thus the
 value of the state global @('guard-checking-on') is reverted to its initial
 value (which was assume here is the default, @('t')) after the @('make-event')
 form completes execution.</p>

 <p><b>Remarks on @('*Protected-system-state-globals*') for advanced
 users.</b></p>

 <ul>

 <li>The constant @('*protected-system-state-globals*') is defined to include
 all built-in state globals, <i>except</i> for those that the ACL2 implementors
 have decided can safely retain values set during @('make-event') expansion.
 If you find state globals that you would like to be added to this list of
 exceptions, please contact the ACL2 implementors.  Note for example that it
 would not be safe to allow @('guard-checking-on') as an exception, since ACL2
 relies on the persistence of this state global's value after each event
 (for explanation, see the Essay on Guard Checking in the ACL2 sources).</li>

 <li>As noted in a comment in the example above, the macro @(tsee
 set-guard-checking) sets the state global, @(''guard-checking-on').  A natural
 question is how one might know this.  For most ACL2 users (one might say,
 traditional ACL2 users), it should suffice simply not to expect system state
 modifications (like the state of guard-checking) to persist after executing a
 @('make-event') form.  For system implementors, one however needs to work with
 the ACL2 system by looking at the definition of the utility &mdash; in this
 example, @('set-guard-checking') &mdash; or at the least, get a sense of its
 expansion by using macroexpansion (for example see @(see trans1)).</li>

 </ul>

 <h3>Advanced Expansion Control</h3>

 <p>We conclude this @(see documentation) section by discussing additional
 control over @('make-event') expansion.  The discussion below is split into
 the following parts; further discussion follows.  The first three parts are
 illustrated in community book
 @('books/make-event/make-event-keywords-or-exp.lisp').</p>

 <p>(1) The value produced by expansion may have the form @('(:DO-PROOFS
 exp)'), which specifies @('exp') as the expansion result, to be evaluated
 without skipping proofs even when including a book.</p>

 <p>(2) The value produced by expansion may have the form @('(:OR exp-1
 ... exp-k)'), which specifies that the first form @('exp-i') to evaluate
 without error is the expansion result.</p>

 <p>(3) The keyword argument @(':EXPANSION?') can serve to eliminate the
 storing of @('make-event') replacements, as described above for the ``book
 expansion'' of a book.</p>

 <p>(4) In contexts where proofs are normally skipped (see @(see
 ld-skip-proofsp)), the expansion phase normally takes place with proofs
 skipped unless the @(':CHECK-EXPANSION') keyword is supplied a non-@('nil')
 value.  However, proofs can be made to take place unconditionally during the
 expansion phase by using an attachment, as discussed below.</p>

 <p>We now elaborate on each of these.</p>

 <p>(1) @(':DO-PROOFS') ``call'' produced by expansion.</p>

 <p>We have discussed the expansion result produced by the expansion phase of
 evaluating a @('make-event') call.  However, if the expansion phase produces
 an expression of the form @('(:DO-PROOFS exp)'), then the expansion result is
 actually @('exp').  The @(':DO-PROOFS') wrapper indicates that even if proofs
 are currently being skipped (see @(see ld-skip-proofsp)), then evaluation of
 @('exp') should take place with proofs not skipped.  For example, proofs will
 be performed when evaluating the @('make-event') expansion, namely the
 indicated @('defthm') event, in the following example.</p>

 @({
  (set-ld-skip-proofsp t state)
  (make-event '(:DO-PROOFS
                (defthm app-assoc (equal
                                   (append (append x y) z)
                                   (append x y z)))))
 })

 <p>Note that such use of @(':DO-PROOFS') causes proofs to be performed when
 evaluating the expansion while including an uncertified book.  But when
 including a certified book, then unless @(':CHECK-EXPANSION') is supplied a
 non-@('nil') value, the @('make-event') replacement will just be the
 expansion, which does not include the @(':DO-PROOFS') wrapper and hence will
 be evaluated with proofs skipped.</p>

 <p>(2) @(':OR') ``call'' produced by expansion.</p>

 <p>There may be times where you want to try different expansions.  For
 example, the community book @('books/make-event/proof-by-arith.lisp') attempts
 to admit a given event, which we'll denote @('EV'), by trying events of the
 following form as @('BOOK') varies over different community books.</p>

 @({
  (encapsulate
   ()
   (local (include-book BOOK :DIR :SYSTEM))
   EV)
 })

 <p>A naive implementation of this macro would evaluate all such @(tsee
 encapsulate) events until one succeeds, and then return that successful event
 as the expansion.  Then that event would need to be evaluated again!  With
 some hacking one could avoid that re-evaluation by using @(tsee skip-proofs),
 but that won't work if you are trying to create a certified book without
 skipped proofs.  Instead, the implementation creates an expansion of the form
 @('(:OR ev-1 ev-2 ... ev-k)'), where the list @('(ev-1 ev-2 ... ev-k)')
 enumerates the generated encapsulate events.  In general, for this
 ``disjunctive case'' of a result from expansion, each @('ev-i') is evaluated
 in sequence, and the first that succeeds without error is considered to be the
 expansion result &mdash; and a repeat evaluation is avoided.  If evaluation of
 each @('ev-i') results in an error, then so does the @('make-event') call.</p>

 <p>This special use of @(':OR') in a value produced by expansion does not
 permit nesting such as @('(:OR ev-1 (:OR ev-2 ev-3))').  That is, when an
 expansion result is @('(:OR ev-1 ev-2 ... ev-k)'), none of the @('ev-i') may
 be of the form @('(:OR ...)').  Note that it is allowed for @('ev-i') to be a
 call of @('make-event'), even one involving this special use of @(':OR').  If
 @('ev-i') is <tt>(:DO-PROOFS ev-i')</tt>, then @('ev-i'') is considered to be
 the expansion in place of @('ev-i').</p>

 <p>(3) The @(':EXPANSION?') keyword argument.</p>

 <p>If keyword argument @(':EXPANSION?') has a non@('nil') value, then the
 @(':CHECK-EXPANSION') keyword must be omitted or have value @('nil') or
 @('t'), hence not a cons pair.</p>

 <p>The idea of the @(':EXPANSION?') keyword is to give you a way to avoid
 storing expansion results in a book's @(see certificate).  Roughly speaking,
 when the expansion result matches the value of @(':EXPANSION?'), then no
 expansion result is stored for the event by book certification; then when the
 book is later included, the value of @(':EXPANSION?') is used as the
 expansion, thus bypassing the expansion phase.  One could say that the event
 is its own make-event replacement, but it is more accurate to say that there
 is no make-event replacement at all, since nothing is stored in the
 certificate for this event.  Below, we elaborate on make-event replacements
 when @(':EXPANSION?') is used and also discuss other properties of this
 keyword.</p>

 <p>We modify the notion of ``expansion result'' for @('make-event') forms to
 comprehend the use of the @(':EXPANSION?') keyword.  For that purpose, let's
 consider a call of @('make-event') to be ``reducible'' if it has an
 @(':EXPANSION?') keyword with non-@('nil') value, @('exp'), and its
 @(':CHECK-EXPANSION') keyword is missing or has value @('nil'), in which case
 the ``reduction'' of this @('make-event') call is defined to be @('exp').  The
 expansion result as originally defined is modified by the following
 ``recursive reduction'' process: recur through the original expansion, passing
 through calls of @(tsee local), @(tsee skip-proofs), @(tsee with-output),
 @(tsee with-prover-step-limit), and @(tsee with-prover-time-limit), and
 replacing (recursively) any reducible call of @('make-event') by its
 reduction.  Furthermore, we refer to two forms as ``reduction equivalent'' if
 their recursive reductions are equal.  Note that the recursive reduction
 process does not pass through @(tsee progn) or @(tsee encapsulate), but that
 process is applied to the computation of expansions for their subsidiary
 @(tsee make-event) calls.</p>

 <p>To explain further the effect of @(':EXPANSION? exp'), we split into the
 following two cases.</p>

 <p><b>Case 1</b>: Evaluation is not taking place when including a book or
 evaluating the second pass of an @(tsee encapsulate) event; more precisely,
 the value of @('(ld-skip-proofsp state)') is not the symbol @('INCLUDE-BOOK').
 There are two subcases.</p>

 <ul>

 <li>Case 1a: The expansion result is not reduction-equivalent to @('exp').
 Then the @('make-event') call is processed as though the @(':EXPANSION?')
 keyword had been omitted.</li>

 <li>Case 2a: The expansion result is reduction-equivalent to @('exp').  Then
 there is no @('make-event') replacement for this call of @('make-event'); no
 replacement will be put into the @(see certificate) file for a book containing
 this @('make-event') call.  When that book is subsequently included, the
 original form will be evaluated in the manner described in the next
 case.</li>

 </ul>

 <p><b>Case 2</b>: Evaluation is taking place when including a book or evaluating
 the second pass of an @(tsee encapsulate) event; more precisely, the value of
 @('(ld-skip-proofsp state)') is the symbol @('INCLUDE-BOOK').  Then the
 expansion is @('exp').  The expansion phase is skipped unless
 @(':CHECK-EXPANSION') is @('t').</p>

 <p>The @(':EXPANSION?') keyword can be particularly useful in concert with the
 disjunctive (``@(':OR')'') case (2) discussed above.  Suppose that expansion
 produces a value as discussed in (2) above, @('(:OR exp-1 ... exp-k)').  If
 one of these expressions @('exp-i') is more likely than the others to be the
 expansion, then you may wish to specify @(':EXPANSION? exp-i'), as this will
 avoid storing a @('make-event') replacement in that common case.  This could
 be useful if the expressions are large, to avoid enlarging the @(see
 certificate) file for a book containing the @('make-event') call.</p>

 <p>It is legal to specify both @(':EXPANSION? exp') and @(':CHECK-EXPANSION
 t').  When either @('(ld-skip-proofsp state)') is the symbol
 @('INCLUDE-BOOK'), or evaluation is taking place in raw Lisp, then this
 combination is treated the same as if @(':EXPANSION?') is omitted and the
 value of @(':CHECK-EXPANSION') is @('exp').  Otherwise, this combination is
 treated the same as @(':CHECK-EXPANSION t'), modified to accommodate the
 effect of @(':EXPANSION?')  as discussed above: if the expansion is indeed the
 value of @(':EXPANSION?'), then no @('make-event') replacement is
 generated.</p>

 <p>(4) Unconditionally enabling proofs during the expansion phase using an
 attachment.</p>

 <p>Proofs are normally skipped during the expansion phase unless the
 @(':CHECK-EXPANSION') keyword is supplied a non-@('nil') value.  To cause
 proofs to take place unconditionally during the expansion phase, evaluate one
 of the following two forms, as explained below.</p>

 @({
 (defattach (always-do-proofs-during-make-event-expansion
             constant-t-function-arity-0)
   :system-ok t)

 (defattach (always-do-proofs-during-make-event-expansion
             constant-all-function-arity-0)
   :system-ok t)
 })

 <p>The first of these is probably preferred in most cases, since it does not
 have any effect while evaluating an @(tsee include-book) form (more precisely,
 when @('(ld-skip-proofsp state)') is @(''include-book')).  The second removes
 that restriction.</p>

 <p>To restore the default behavior, evaluate the following.</p>

 @({
 (defattach (always-do-proofs-during-make-event-expansion
             constant-nil-function-arity-0)
   :system-ok t)
 })

 <p>(If you would like an explanation of @('defattach') in general, see @(see
 defattach).)</p>")

(defxdoc make-event-details
  :parents (make-event)
  :short "Details on @(tsee make-event) expansion"
  :long "<p>The normal user of @('make-event') can probably ignore this
 section, but we include it for completeness.  We assume that the reader has
 read and understood the basic documentation for @('make-event') (see @(see
 make-event)), but we begin below with a summary of expansion.</p>

 <h3>Introduction</h3>

 <p>Here is a summary of how we handle expansion involving @('make-event')
 forms.</p>

 <p>@('(make-event form :check-expansion nil)')</p>

 <p>This shows the @(':check-expansion') default of @('nil'), and is typical
 user input.  We compute the expansion @('exp') of @('form'), which is the
 expansion of the original @('make-event') expression and is evaluated in place
 of that expression.</p>

 <p>@('(make-event form :check-expansion t)')</p>

 <p>The user presumably wants it checked that the expansion doesn't change in
 the future, in particular during @(tsee include-book).  If the expansion of
 @('form') is @('exp'), then we will evaluate @('exp') to obtain the value as
 before, but this time we record that the expansion of the original
 @('make-event') expression is @('(make-event form :check-expansion exp)')
 rather than simply @('exp').</p>

 <p>@('(make-event form :check-expansion exp) ; exp a cons')</p>

 <p>This is generated for the case that @(':check-expansion') is @('t'), as
 explained above.  Evaluation is handled as described in that above case,
 except here we check that the expansion result is the given @('exp').
 (Actually, the user is also allowed to supply such a form.)  The original
 @('make-event') expression does not undergo any expansion (intuitively, it
 expands to itself).</p>

 <p>Now let us take a brief look at how we expand @(tsee progn) and @(tsee
 encapsulate) forms.  More details are found further below (see ``Detailed
 semantics'').</p>

 <p>@('(progn ... (make-event form ...) ...)')</p>

 <p>The expansion is obtained, roughly speaking, by replacing the
 @('make-event') form by its expansion, @('exp'), except that if
 @(':check-expansion exp') is supplied explicitly, then no such replacement
 takes place.</p>

 <p>Expansion for @('(encapsulate ... (make-event form ...) ...)') is similar
 to the case for @('progn'), except that if the expansion of @('form') is
 @('exp'), then what is stored is @('(record-expansion (make-event form ...)
 exp)').  Also as for @('progn'), the exception is that when
 @(':check-expansion exp') is supplied explicitly, no such replacement takes
 place.  Here, @('record-expansion') is a macro that simply returns its second
 argument, but is used for checking redundancy of @('encapsulate') forms (see
 @(see redundant-encapsulate)).</p>

 <p>Certain ``wrappers'' around a @('make-event') are restored as the last part
 of the expansion process, in particular for @('make-event') calls that are
 inside calls of @(tsee encapsulate) or @(tsee progn), as well as in events
 processed during a book's certification, including @(see portcullis) commands
 from the certification @(see world).  For example, if you evaluate a form
 @('(local (with-prover-step-limit 100 (make-event ...)))')  where the
 @('make-event') call has expansion @('<exp>'), and then you certify a book,
 the book's @(see certificate) file will include among its portcullis commands
 the form @('(local (with-prover-step-limit 100 <exp>))').  Macroexpansion is
 performed to determine the wrappers.  The wrappers thus restored are as
 follows.</p>

 @({
 local
 skip-proofs
 with-cbd
 with-guard-checking-event
 with-output
 with-prover-step-limit
 with-prover-time-limit
 })

 <p>The discussion below references this process as the final expansion being
 ``rebuilt from'' the form.</p>

 <h3>Detailed semantics</h3>

 <p>In our explanation of the semantics of @('make-event'), we assume
 familiarity with the notion of ``embedded event form'' (see @(see
 embedded-event-form)).</p>

 <p>Let's say that the ``actual embedded event form'' corresponding to a given
 form is the underlying call of an ACL2 event: that is, @(tsee LOCAL)s are
 dropped when @('ld-skip-proofsp') is @(''include-book'), and macros are
 expanded away, thus leaving us with a @(tsee progn), a @(tsee make-event), or
 an event form (possibly @(tsee encapsulate)), any of which might have
 surrounding @(tsee local), @(tsee skip-proofs), or @(tsee with-output)
 calls.</p>

 <p>Thus, such an actual embedded event form can be viewed as having the form
 @('(rebuild-expansion wrappers base-form)') where @('base-form') is a
 @('progn'), a @('make-event'), or an event form (possibly @('encapsulate')),
 and @('wrappers') are (as in ACL2 source function @('destructure-expansion'))
 the result of successively removing the event form from the result of
 macroexpansion, leaving a sequence of @('(local)'), @('(skip-proofs)'), and
 @('(with-output ...)') forms.  In this case we say that the form
 ``destructures into'' the indicated @('wrappers') and @('base-form'), and that
 it can be ``rebuilt from'' those @('wrappers') and @('base-form').</p>

 <p>Elsewhere we define the notion of the ``expansion result'' from an
 evaluation (see @(see make-event)), and we mention that when expansion
 concludes, the ACL2 logical @(see world) and most of the @('state') are
 restored to their pre-expansion values.  Specifically, after evaluation of the
 argument of @('make-event') (even if it is aborted), the ACL2 logical world is
 restored to its pre-evaluation value, as are all state global variables in the
 list @('*protected-system-state-globals*').  Thus, assignments to user-defined
 state globals (see @(see assign)) do persist after expansion, since they are
 not in that list.</p>

 <p>We recursively define the combination of evaluation and expansion of an
 embedded event form as shown below.  We also simultaneously define the notion
 of ``expansion takes place,'' which is assumed to propagate upward (in a sense
 that will be obvious), such that if no expansion takes place, then the
 expansion of the given form is considered to be itself.  It is useful to keep
 in mind a goal that we will consider later: Every @('make-event') subterm of
 an expansion result has a @(':check-expansion') field that is a @(tsee consp),
 where for this purpose @('make-event') is viewed as a macro that returns its
 @(':check-expansion') field.</p>

 <blockquote>

 <p>If the given form is not an embedded event form, then simply cause a soft
 error, @('(mv erp val state)') where @('erp') is not @('nil').  Otherwise:</p>

 <p>If the evaluation of the given form does not take place (presumably because
 @(tsee local) events are being skipped), then no expansion takes place.
 Otherwise:</p>

 <p>Let @('x') be the actual embedded event form corresponding to the given
 form, which destructures into wrappers @('W') and base-form @('B').  Then the
 original form is evaluated by evaluating @('x'), and its expansion is as
 follows.</p>

 <p>If @('B') is @('(make-event form :check-expansion val)'), then expansion
 takes place if and only if @('val') is not a @('consp') and no error occurs,
 as now described.  Let @('R') be the expansion result from protected
 evaluation of @('form'), if there is no error.  @('R') must be an embedded
 event form, or it is an error.  Then evaluate/expand @('R'), where if @('val')
 is not @('nil') then state global @(''ld-skip-proofsp') is initialized to
 @('nil').  (This initialization is important so that subsequent expansions are
 checked in a corresponding environment, i.e., where proofs are turned on in
 both the original and subsequent environments.)  It is an error if this
 evaluation causes an error.  Otherwise, the evaluation yields a value, which
 is the result of evaluation of the original @('make-event') expression, as
 well as an expansion, @('E_R').  Let @('E') be rebuilt from @('W') and
 @('E_R').  The expansion of the original form is @('E') if @('val') is
 @('nil'), and otherwise is the result of replacing the original form's
 @(':check-expansion') field with @('E'), with the added requirement that if
 @('val') is not @('t') (thus, a @('consp')) then @('E') must equal @('val') or
 else we cause an error.</p>

 <p>If @('B') is @('(progn form1 form2 ...)') (and similarly for @(tsee
 progn!)), and at least one @('formi') has an expansion, then the expansion of
 the original form is obtained by replacing each @('formi') by its expansion
 and then rebuilding the entire @('progn') call from @('B').</p>

 <p>If @('B') is @('(encapsulate sigs form1 form2 ...)'), then after evaluating
 @('B'), the expansion of the original form is the result of rebuilding from
 @('B'), with wrappers @('W'), after replacing each @('formi') in @('B') for
 which expansion takes place by <tt>(record-expansion formi formi')</tt>, where
 @('formi'') is the expansion of @('formi').  Note that these expansions are
 determined as the @('formi') are evaluated in sequence (where in the case of
 @('encapsulate'), this determination occurs only during the first pass).
 Except, if no expansion takes place for any @('formi'), then the expansion of
 the original form is itself.</p>

 <p>Otherwise, the expansion of the original form is itself.</p>

 </blockquote>

 <p>(Optional Implementation Notes.  The latest expansion of a @(tsee
 make-event), @(tsee progn), @(tsee progn!), or @(tsee encapsulate) is
 temporarily stored in state global @(''last-make-event-expansion'), except
 that if no expansion has taken place for that form then
 @(''last-make-event-expansion') has value @('nil').  Expansions ultimately
 show up in the world's @(tsee command) tuples; for example, immediately after
 processing a command its expansion is
 @('(access-command-tuple-last-make-event-expansion (cddr (car (w state))))').
 Top-level expansions do not include rebuilding of wrappers, although such
 wrappers are restored when constructing @(see portcullis) commands as
 discussed above.  End of Implementation Notes.)</p>

 <p>Similarly to the @(tsee progn) and @(tsee encapsulate) cases above, book
 certification causes a book to be replaced by its so-called ``book
 expansion,'' where each event @('ev') for which expansion took place during
 the proof pass of certification is replaced by its expansion, but with certain
 @(tsee local) events elided.</p>

 <p>Optional Implementation Note.  The book expansion is actually implemented
 by way of the @(':expansion-alist') field of its @(see certificate), which
 associates 0-based positions of top-level forms in the book (not including the
 initial @(tsee in-package) form) with their expansions.  Thus, the book's
 source file is not overwritten; rather, the certificate's expansion-alist is
 applied when the book is included or compiled.  End of Implementation
 Note.</p>

 <p>It is straightforward by computational induction to see that for any
 expansion of an embedded event form, every @('make-event') sub-event has a
 @(tsee consp) @(':check-expansion') field.  Here, by ``sub-event'' we mean to
 expand macros; and we also mean to traverse @('progn') and @('encapsulate')
 forms as well as @(':check-expansion') fields of @('make-event') forms.  Thus,
 we will only see @('make-event') forms with @('consp') @(':check-expansion')
 fields in the course of @('include-book') forms, the second pass of
 @('encapsulate') forms, and raw Lisp.  This fact guarantees that an event form
 will always be treated as its original expansion.</p>

 <h3>Notes on ttags</h3>

 <p>See @(see defttag) for documentation of the notion of ``trust tag''
 (``ttag'').  We note here that even if an event @('(defttag tag-name)') for
 non-@('nil') @('tag-name') is admitted only during the expansion phase of a
 @(tsee make-event) form, then such expansion will nevertheless still cause
 @('tag-name') to be recorded in the logical @(see world) (assuming that the
 @('make-event') form is admitted).  So in order to certify such a book, a
 suitable @(':ttags') argument must be supplied; see @(see certify-book).</p>

 <p>ACL2 does provide a way to avoid the need for @(':ttags') arguments in such
 cases.  The idea is to certify a book twice, where the results of
 @('make-event') expansion are saved from the first call of @(tsee
 certify-book) and provided to the second call.  See @(see
 set-write-acl2x).</p>

 <p>Finally, we discuss a very unusual case where certification does not
 involve trust tags but a subsequent @(tsee include-book) does involve trust
 tags: a @('make-event') call specifying @(':check-expansion t'), whose
 expansion generates a @(tsee defttag) event during @(tsee include-book) but
 not @(tsee certify-book).  Consider the following book.</p>

 @({
  (in-package "ACL2")
  (make-event
   (er-progn
    (if (@ skip-notify-on-defttag) ; non-nil when including a certified book
        (pprogn
         (fms "Value of (@ skip-notify-on-defttag): ~x0~|"
              (list (cons #0 (@ skip-notify-on-defttag)))
              *standard-co* state nil)
         (encapsulate
          ()
          (defttag :foo)
          (value-triple "Imagine something bad here!")))
      (value nil))
    (value '(value-triple :some-value)))
   :check-expansion t)
 })

 <p>This book certifies successfully without the need for a @(':ttags')
 argument for @(tsee certify-book).  Indeed, the above book's @(see
 certificate) does not specify @(':foo') as a trust tag associated with the
 book, because no @('defttag') event was executed during book certification.
 Unfortunately, if we try to include this book without specifying a value of
 @(':ttags') that allows @(':foo'), book inclusion will cause executing of the
 above @(tsee defttag).  If that inclusion happens in the context of certifying
 some superior book and the appropriate @(':ttags') arguments have not been
 provided, that certification will fail.</p>

 <h3>Expansion errors and the @(':ON-BEHALF-OF') keyword argument</h3>

 <p>Consider the case that expansion returns an @(see error-triple) @('(mv erp
 val state)'), where @('erp') is not @('nil').  Then @('make-event') may
 conclude with an error message, as follows.</p>

 <ul>

 <li>If keyword @(':ON-BEHALF-OF') has value @(':quiet!') then there is no such
 concluding error message.</li>

 <li>Otherwise, if @('erp') is a string, then the concluding error message is
 produced by printing @('erp') with the call @('(er soft ctx erp)'), where
 @('ctx') is the context (see @(see ctx)).</li>

 <li>Otherwise, if @('erp') is a message (see @(see msg)), then the concluding
 error message is produced by the call @('(er soft ctx "~@0" erp)'), where
 @('ctx') is the context (see @(see ctx)).</li>

 <li>Otherwise, if keyword @(':ON-BEHALF-OF') has value @(':quiet') then there
 is no concluding error message.</li>

 <li>Otherwise, if keyword @(':ON-BEHALF-OF') is not supplied or has value
 @('nil') &mdash; so we are now in the typical case &mdash; then the concluding
 error message is ``Error in MAKE-EVENT from expansion of:'' followed by the
 form.</li>

 <li>Otherwise, keyword @(':ON-BEHALF-OF') has a value @('x') other than
 @(':quiet!'), @(':quiet'), or @('nil'), in which case the concluding error
 message is as just above, except that after ``Error in MAKE-EVENT'' is
 stated ``on behalf of'' followed by @('x').</li>

 </ul>

 <p>Note that errors generated during expansion are not affected by the cases
 above; those only control the concluding error message, if any.</p>

 <h3>The @(':save-event-data') keyword argument</h3>

 <p>See @(see get-event-data) for relevant background on data stored for each
 event.  The association list stored in @('last-event-data') is normally
 replaced every time an event concludes (at the summary phase), and that holds
 for calls of @('make-event').  But there is the following exception: when
 @('make-event') is called with a non-@('nil') value for keyword
 @(':save-event-data'), then that association list persists from the expansion
 phase.  This is how the @(tsee thm) macro is able to populate the
 @('last-event-data') association list without having that list be smashed when
 the surrounding @('make-event') (used for implementing @('thm'))
 concludes.</p>")

(defxdoc make-event-example-1
  :parents (make-event)
  :short "An example use of @(tsee make-event)"
  :long "<p>Here, we develop a reasonably self-contained example that
 illustrates how to use @('make-event') to develop tools, by solving a
 challenge posed by Alessandro Coglio.  For another such example, see @(see
 make-event-example-2).</p>

 <p>The challenge is to develop a programmatic method for solving the following
 sort of problem.</p>

 <ol>

 <li>Create a @(tsee defun) form.</li>

 <li>Submit it to ACL2, obtaining a new ACL2 @(see state) whose @(see world)
 includes the function just submitted.</li>

 <li>Access various elements of this function (e.g., unnormalized body).</li>

 <li>Create and return a new @('defun') that's based on elements of the
 previous one.</li>

 <li>Submit this new defun via a @(tsee make-event), but in a state that does
 not include the previous @('defun').</li>

 </ol>

 <p>We illustrate how to do this sort of thing by specifying the ``new
 @('defun') that's based on elements of the previous one'' to be as follows:
 add the formal, @('y'), and modify the body so that @('y') is consed onto the
 old body.  Of course, this is a trivial example that could be done without
 @('make-event'); but we solve it in a way that shows how to solve any such
 problem.  For simplicity, let's not worry about the case that @('y') is
 already a formal of the existing @('defun').  Here are the main steps.</p>

 <ul>

 <li>(a) Submit the @('defun').</li>

 <li>(b) Gather information from the resulting world.  In this case, we access
 the formals and body of the definition.</li>

 <li>(c) Create the desired event.</li>

 </ul>

 <p>The following code does those three things, as explained in comments below,
 which include references to the three steps above.</p>

 @({
 (er-progn

 ; Each of the two forms below returns an error triple (see :DOC
 ; error-triple), so we can evaluate both by using er-progn, which
 ; returns the last (second) error triple.

  (defun foo (x) (cons x x)) ; (a)
  (let ((formals (formals 'foo (w state))) ; (b)
        (body (body 'foo nil (w state))))
    (value `(defun foo ,(cons 'y formals) ; (c)
              (cons y ,body)))))
 })

 <p>So far so good: we have computed an error triple @('(mv nil val state)')
 whose value component, @('val'), is the desired @('defun') form.  However,
 that leaves us in a world that includes the first @('defun') form.  For a
 solution to the original challenge (for our specific case), that must not be
 the case, and moreover the second @('defun') form should be included in the
 current world.  Fortunately, @(tsee make-event) is perfectly suited to do both
 of these things.  Consider the following form, which simply wraps
 @('make-event') around the code displayed just above.</p>

 @({
 (make-event (er-progn
              (defun foo (x) (cons x x))
              (let ((formals (formals 'foo (w state)))
                    (body (body 'foo nil (w state))))
                (value `(defun foo ,(cons 'y formals)
                          (cons y ,body))))))
 })

 <p>The expansion phase (see @(see make-event)) computes the new @('defun')
 form &mdash; the one with the extra formal and modified body &mdash; and then
 that new @('defun') form is evaluated in the original world, which does not
 include the first @('defun') form.</p>

 <p>We complete the job by making a programmatic solution, with a macro that
 expands to such a @('make-event') form.  We make it nice by inhibiting all
 output except error output.</p>

 @({
 (defmacro cons-y-onto-body (def new-name)
   `(make-event
     (with-output!
       :off :all
       :on error
       (er-progn
        ,def
        (let* ((name ',(cadr def))
               (new-name ',new-name)
               (formals (formals name (w state)))
               (body (body name nil (w state))))
          (value (list 'defun new-name (cons 'y formals)
                       (list 'cons 'y body))))))
     :on-behalf-of :quiet!))
 })

 <p>This could be improved by doing some error checking, but we leave that as
 an exercise.</p>

 <p>Below is a log, with comments added, that shows uses of the macro
 above.</p>

 @({
 ; First we call the macro successfully.  Notice that although we inhibited
 ; output during the expansion phase (using with-output!), below we see output
 ; from the resulting new defun event.

 ACL2 !>(cons-y-onto-body (defun f (x) x) new-f)

 Since NEW-F is non-recursive, its admission is trivial.  We observe
 that the type of NEW-F is described by the theorem (CONSP (NEW-F Y X)).
 We used primitive type reasoning.

 Summary
 Form:  ( DEFUN NEW-F ...)
 Rules: ((:FAKE-RUNE-FOR-TYPE-SET NIL))
 Time:  0.01 seconds (prove: 0.00, print: 0.00, other: 0.01)

 Summary
 Form:  ( MAKE-EVENT (WITH-OUTPUT! :OFF ...) ...)
 Rules: NIL
 Time:  0.03 seconds (prove: 0.00, print: 0.00, other: 0.03)
  NEW-F
 ACL2 !>:pe new-f ; Check that the new definition was indeed submitted.
  L         2:x(CONS-Y-ONTO-BODY (DEFUN F # ...) NEW-F)
               
 >L             (DEFUN NEW-F (Y X) (CONS Y X))
 ACL2 !>:pe f ; Check that the old definition was NOT submitted.


 ACL2 Error in :PE:  The object F is not a logical name.  See :DOC logical-
 name.

 ; The defun below is ill-formed, so we get an error when it is submitted,
 ; during the expansion phase.  Our use of with-output! allowed error messages,
 ; so we see the error message in this case.

 ACL2 !>(cons-y-onto-body (defun g (x) (+ y y)) new-g)


 ACL2 Error in ( DEFUN G ...):  The body of G contains a free occurrence
 of the variable symbol Y.


 Summary
 Form:  ( MAKE-EVENT (WITH-OUTPUT! :OFF ...) ...)
 Rules: NIL
 Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)

 ACL2 Error in ( MAKE-EVENT (WITH-OUTPUT! :OFF ...) ...):  See :DOC
 failure.

 ******** FAILED ********
 ACL2 !>
 })")

(defxdoc make-event-example-2
  :parents (make-event)
  :short "An example use of @(tsee make-event)"
  :long "<p>Here, we develop a reasonably self-contained example that
 illustrates how to use @('make-event') to develop tools.  For another such
 example, see @(see make-event-example-1).  We thank Yan Peng for putting
 forward this problem.</p>

 <p>We begin by discussing prerequisites for this presentation.  Next, we
 present the challenge problem, followed by code that solves the problem
 together with an example that illustrates its use.  Finally, we start from the
 beginning and show how to develop the solution step-by-step.</p>

 <h3>Prerequisites</h3>

 <p>We assume some general ACL2 and Common Lisp background, including
 familiarity with @(see macros) and backquote.  But we do some programming
 below that goes beyond that general background in our use of the ACL2 @(see
 state).  See @(see programming-with-state) for relevant discussion, including
 state global variables, @(tsee f-get-global), @(tsee f-put-global), @(see
 error-triple)s and their construction using @('value'), @(tsee value-triple),
 and @(tsee pprogn).  We also assume familiarity with both @(tsee progn) and
 the notion of legal event form; see @(see embedded-event-form).  If you are
 not familiar with these notions, then the discussion below might still make
 some sense, but you might need to read about these notions in order to
 complete your understanding.</p>

 <p>Next, we present the challenge problem that we will solve below.</p>

 <h3>Challenge problem</h3>

 <blockquote><p>Define a utility that evaluates a given sequence of
 @(see events), even continuing past errors, which stores the list of event
 forms that caused errors.</p></blockquote>

 <p>Let us call this utility @('progn+'), since it can be viewed as an
 enhancement of @(tsee progn).  So a successful solution should allow us to
 evaluate the following form to define function symbols @('f1'), @('f2'), and
 @('f3'), as well as the event @('good-thm'), and also store the events for
 @('bad-thm') and @('bad-fn').</p>

 @({
 (progn+ (defun f1 (x) x)
         (defthm good-thm (equal 1 1) :rule-classes nil)
         (value-triple (cw "@@HI~%"))
         (defthm bad-thm (equal x y) :rule-classes nil) ; error!
         (defun f2 (x) x)
         (defun bad-fn (x) y) ; error!
         (defun f3 (x) x)
         )
 })

 <p>We next present a definition of @('progn+'), together with output from the
 example displayed above.  After that we will start from the beginning and
 describe how one might develop @('progn+') from scratch.</p>

 <h3>The completed code and a test</h3>

 @({

 (defmacro save-progn+-error (x)
   `(make-event
     (pprogn (f-put-global 'progn+-errors
                           (cons ,x
                                 (f-get-global 'progn+-errors state))
                           state)
             (value '(value-triple nil)))))

 (defun progn+-fn (lst)
   (declare (xargs :guard (true-listp lst) :mode :program))
   (cond ((endp lst) nil)
         (t (cons `(make-event '(:or ,(car lst) (save-progn+-error ',(car lst))))
                  (progn+-fn (cdr lst))))))

 (defmacro progn+ (&rest lst)
   (declare (xargs :guard (and (true-listp lst)
                               lst)))
   `(progn (make-event (pprogn (f-put-global 'progn+-errors nil state)
                               (value '(value-triple nil))))
            ,@(progn+-fn lst)))

 ; Example:
 (progn+ (defun f1 (x) x)
         (defthm good-thm (equal 1 1) :rule-classes nil)
         (value-triple (cw "@@HI~%"))
         (defthm bad-thm (equal x y) :rule-classes nil)
         (defun f2 (x) x)
         (defun bad-fn (x) y)
         (defun f3 (x) x)
         )
 })

 <p>After running the example (which is the final form above), we expect the
 resulting logical @(see world) to contain definitions of function symbols
 @('f1'), @('f2'), and @('f3'), as well as the event @('good-thm'), but that no
 events would be stored for @('bad-thm') or @('bad-fn').  Moreover, we expect
 that a state global variable holds the event forms for @('bad-thm') and
 @('bad-fn').  Let us check that all of these expectations are met.</p>

 @({
 ACL2 !>:pe f1
            4:x(PROGN+ (DEFUN F1 # ...)
                       (DEFTHM GOOD-THM # ...)
                       ...)
               
 >L             (DEFUN F1 (X) X)
 ACL2 !>:pe f2
            4:x(PROGN+ (DEFUN F1 # ...)
                       (DEFTHM GOOD-THM # ...)
                       ...)
               
 >L             (DEFUN F2 (X) X)
 ACL2 !>:pe f3
            4:x(PROGN+ (DEFUN F1 # ...)
                       (DEFTHM GOOD-THM # ...)
                       ...)
               
 >L             (DEFUN F3 (X) X)
 ACL2 !>(@ progn+-errors) ; same as (f-get-global 'progn+-errors state)
 ((DEFUN BAD-FN (X) Y)
  (DEFTHM BAD-THM (EQUAL X Y)
          :RULE-CLASSES NIL))
 ACL2 !>
 })

 <h3>Development of the solution</h3>

 <p>We now start from the beginning.  Recall that @(tsee progn) does almost
 what we ask @('progn+') to do, except that @(tsee progn) stops at the first
 error.  So our approach will be to define a macro that is much like
 @('progn'), except that each event is modified as follows: if evaluation fails
 for an event, then that event is pushed onto the value of a specific state
 global (see @(see programming-with-state)), @('progn+-errors').  Moreover,
 since @(tsee progn) is applied only to legal event forms (see @(see
 embedded-event-form)), we need this modification to be a legal event form,
 too.  Fortunately, a call of @(tsee make-event) is a legal event form.  So our
 plan is for @('(progn+ ... <event> ...)') to expand to a call @('(progn
 ... (make-event ...) ...)') so that the indicated @('make-event') call
 attempts to evaluate @('<event>'), and if that attempt fails, then
 @('<event>') it is pushed onto @('progn+-errors').</p>

 <p>Thus, we begin with a simple piece of the task, by showing how to create an
 event that will push a specific form, @('(defthm bad-thm (equal x
 y) :rule-classes nil)'), onto @('progn+-errors').</p>

 @({
 (make-event
  (pprogn (f-put-global 'progn+-errors
                        (cons '(defthm bad-thm (equal x y) :rule-classes nil)
                              (f-get-global 'progn+-errors state))
                        state)
          (value '(value-triple nil))))
 })

 <p>It might seem more natural to write @('(f-put-global ...)'), instead of the
 more complex @('(pprogn (f-put-global ...) (value '(value-triple nil)))').
 However, the argument to @('make-event') must evaluate to either: (1) a legal
 event form; or (2) an @(see error-triple), @('(mv nil x state)'), where @('x')
 is a legal event form.  Since the @('f-put-global') call modifies state, (1)
 is not an option; so we choose (2).  Since the role of @('x') is only to
 provide an event form, we choose @('x') to be the trivial event form
 @('(value-triple nil)').</p>

 <p>We follow good programming practice by wrapping the functionality displayed
 above into a concise utility, as follows.</p>

 @({
 (defmacro save-progn+-error (x)
 ; Push x (which is evaluated) onto the value of state global 'progn+-errors.
   `(make-event
     (pprogn (f-put-global 'progn+-errors
                           (cons ,x
                                 (f-get-global 'progn+-errors state))
                           state)
             (value '(value-triple nil)))))
 })

 <p>Before we write @('progn+'), it helps to approximate its expansion in the
 specific ``Example'' displayed above.  We know in advance which two forms will
 fail, so we `cheat' by using @('progn') but with those two forms replaced by
 calls to @('save-progn+-error').</p>

 @({
 (f-put-global 'progn+-errors nil state)
 (progn  (defun f1 (x) x)
         (defthm good-thm (equal 1 1) :rule-classes nil)
         (value-triple (cw "@@HI~%"))
         (save-progn+-error
          '(defthm bad-thm (equal x y) :rule-classes nil))
         (defun f2 (x) x)
         (save-progn+-error
          '(defun bad-fn (x) y))
         (defun f3 (x) x)
         )
 })

 <p>Our next task is to find a way to tell ACL2 that it should run a given
 event, and if that event fails it should save it using @('save-progn+-error').
 Fortunately, the @(':OR') keyword of @(tsee make-event) is perfect for this
 task.  Consider the following two examples.</p>

 @({
 (make-event '(:or (defun f2 (x) x)
                   (save-progn+-error '(defun f2 (x) x))))

 (make-event '(:or (defun bad-fn (x) y)
                   (save-progn+-error '(defun bad-fn (x) y))))
 })

 <p>In the first example, @('make-event') invokes the given call of @(tsee
 defun), which runs without error; and @('make-event') then exits without
 error.  In the second example, @('make-event') invokes the given call of
 @('defun'), which causes an error; so then @('make-event') evaluates the
 second argument of the @(':OR'), to invoke @('save-progn+-error') on that same
 @('defun') call.  Since that call of @('save-progn+-error') evaluates without
 error (because it expands to @('(value-triple nil)')), the @('make-event')
 call exits without error.  See @(see make-event) for more information about
 the @(':OR') keyword.</p>

 <p>We can now define @('progn+') to be the result of modifying each of its
 forms as in the two examples displayed just above.  First we write a function
 that transforms a list by applying that modification to each of its
 members.</p>

 @({
 (defun progn+-fn (lst)
   (declare (xargs :guard (true-listp lst) :mode :program))
   (cond ((endp lst) nil)
         (t (cons `(make-event '(:or ,(car lst) (save-progn+-error ',(car lst))))
                  (progn+-fn (cdr lst))))))
 })

 <p>We complete our definition of @('progn+'), by generating a @('progn') call
 with the desired modification of each form in the list, using @('progn+-fn')
 &mdash; but preceded by yet another @('make-event') call, this one for
 initializing our state global to @('nil').</p>

 @({
 (defmacro progn+ (&rest lst)
   (declare (xargs :guard (and (true-listp lst)
                               lst)))
   `(progn (make-event (pprogn (f-put-global 'progn+-errors nil state)
                               (value '(value-triple nil))))
            ,@(progn+-fn lst)))
 })

 <p><b>Exercise</b>: Modify this tool so that instead of merely updating a
 state global, it prints the failed events at the end of execution; and
 moreover, it prints them in their original order.  See @(see
 make-event-example-2-exercise) for a solution.</p>")